facebook-messenger 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f7c4706fe8ba78595fea5ecb1cd09c272b888d5
-  data.tar.gz: 0c92e230627849cbf801f5b65e64b3d4f86df070
+  metadata.gz: e91c65dbe461f44e0516eab4311854cb1e346c67
+  data.tar.gz: 8986a3265e3c79aa89ee77476569d6a9a45aa652
 SHA512:
-  metadata.gz: b36ffd86c6f2ae36f412295e830ae704dff9352f37da76fe9bd9539d0789dc9e7093d36a6e60212a1154aab532e87e2f134da03c2c0d1184d26589c4253c62c4
-  data.tar.gz: f62d1a3a1122d0feea5c2aaa36116db5538c44c1358bb308091716c0e04ca93b3377c2e5017384e4dac0904b2af1f948ff63dce2cc6b2b20a6be5b64681199e6
+  metadata.gz: 03b239d5a2531fe9f11f483898a76b62c64cb24eb5ab3ae65230600c94485ac522e60526d8513be0718bfb85efc123b3e3c0a6bb0f479d7369783fc837822e7e
+  data.tar.gz: 4b22c9a53f9021b8725edb330fe48397b9bd51a571aa9bc85a5982eeef65902b064b171cbd6104848c32ff6d2c875aa823f4b4c51eda754e617d9c7e17e1b510

data/README.md

@@ -41,15 +41,14 @@ end
 ... or even send the human messages out of the blue:
 
 ```ruby
-Bot.deliver(
+Bot.deliver({
   recipient: {
     id: '45123'
   },
   message: {
     text: 'Human?'
-  },
-  access_token: ENV['ACCESS_TOKEN']
-)
+  }
+}, access_token: ENV['ACCESS_TOKEN'])
 ```
 
 ##### Messages with images
@@ -73,7 +72,7 @@ The human may appreciate hints:
 
 ```ruby
 message.reply(
-  text: 'Human, who is your favorite bot?'
+  text: 'Human, who is your favorite bot?',
   quick_replies: [
     {
       content_type: 'text',
@@ -126,7 +125,37 @@ end
 Show the human you are preparing a message for them:
 
 ```ruby
-message.type
+Bot.on :message do |message|  
+  message.typing_on
+
+  # Do something expensive
+
+  message.reply(text: 'Hello, human!')
+end
+```
+
+Or that you changed your mind:
+
+```ruby
+Bot.on :message do |message|  
+  message.typing_on
+
+  if # something
+    message.reply(text: 'Hello, human!')
+  else
+    message.typing_off
+  end
+end
+```
+
+##### Mark as viewed
+
+You can mark messages as seen to keep the human on their toes:
+
+```ruby
+Bot.on :message do |message|
+  message.mark_seen
+end
 ```
 
 #### Send to Facebook
@@ -161,24 +190,38 @@ Bot.on :delivery do |delivery|
 end
 ```
 
+#### Referral
+
+When the human follows a m.me link with a ref parameter like http://m.me/mybot?ref=myparam,
+you will receive a `referral` event.
+
+```ruby
+Bot.on :referral do |referral|
+  referral.sender    # => { 'id' => '1008372609250235' }
+  referral.recipient # => { 'id' => '2015573629214912' }
+  referral.sent_at   # => 2016-04-22 21:30:36 +0200
+  referral.ref       # => 'MYPARAM'
+end
+```
+
 #### Change thread settings
 
 You can greet new humans to entice them into talking to you:
 
 ```ruby
-Facebook::Messenger::Thread.set(
+Facebook::Messenger::Thread.set({
   setting_type: 'greeting',
   greeting: {
     text: 'Welcome to your new bot overlord!'
-  }
-)
+  },
+}, access_token: ENV['ACCESS_TOKEN'])
 ```
 
 You can define the action to trigger when new humans click on the Get
 Started button. Before doing it you should check to select the messaging_postbacks field when setting up your webhook.
 
 ```ruby
-Facebook::Messenger::Thread.set(
+Facebook::Messenger::Thread.set({
   setting_type: 'call_to_actions',
   thread_state: 'new_thread',
   call_to_actions: [
@@ -186,13 +229,13 @@ Facebook::Messenger::Thread.set(
       payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_WELCOME'
     }
   ]
-)
+}, access_token: ENV['ACCESS_TOKEN'])
 ```
 
 You can show a persistent menu to humans.
 
 ```ruby
-Facebook::Messenger::Thread.set(
+Facebook::Messenger::Thread.set({
   setting_type: 'call_to_actions',
   thread_state: 'existing_thread',
   call_to_actions: [
@@ -212,7 +255,7 @@ Facebook::Messenger::Thread.set(
       url: 'http://example.com/'
     }
   ]
-)
+}, access_token: ENV['ACCESS_TOKEN'])
 ```
 
 ## Configuration

data/lib/facebook/messenger/bot.rb

@@ -1,3 +1,6 @@
+require 'facebook/messenger/bot/error_parser'
+require 'facebook/messenger/bot/exceptions'
+
 module Facebook
   module Messenger
     # The Bot module sends and receives messages.
@@ -7,7 +10,7 @@ module Facebook
       base_uri 'https://graph.facebook.com/v2.6/me'
 
       EVENTS = [:message, :delivery, :postback, :optin,
-                :read, :account_linking].freeze
+                :read, :account_linking, :referral].freeze
 
       class << self
         # Deliver a message with the given payload.
@@ -26,9 +29,9 @@ module Facebook
                             access_token: access_token
                           }
 
-          raise_errors_from(response)
+          Facebook::Messenger::Bot::ErrorParser.raise_errors_from(response)
 
-          response['message_id']
+          response.body
         end
 
         # Register a hook for the given event.
@@ -66,34 +69,6 @@ module Facebook
           $stderr.puts "Ignoring #{event} (no hook registered)"
         end
 
-        # 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']
-
-          raise(
-            error_class_from_error_code(error['code']),
-            (error['error_data'] || error['message'])
-          )
-        end
-
-        # Find the appropriate error class for the given error code.
-        #
-        # error_code - An Integer describing an error code.
-        #
-        # Returns an error class, or raises KeyError if none was found.
-        def error_class_from_error_code(error_code)
-          {
-            100 => RecipientNotFound,
-            10 => PermissionDenied,
-            2 => InternalError
-          }[error_code] || Facebook::Messenger::Error
-        end
-
         # Return a Hash of hooks.
         def hooks
           @hooks ||= {}
@@ -113,10 +88,6 @@ module Facebook
           )
         end
       end
-
-      class RecipientNotFound < Facebook::Messenger::Error; end
-      class PermissionDenied < Facebook::Messenger::Error; end
-      class InternalError < Facebook::Messenger::Error; end
     end
   end
 end

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.keys.include? error_code
+          end
+
+          def access_token_error?(error_code)
+            ACCESS_TOKEN_ERROR_CODES.keys.include? error_code
+          end
+
+          def account_linking_error?(error_code)
+            ACCOUNT_LINKING_ERROR_CODES.keys.include? 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/error.rb

@@ -1,5 +1,31 @@
 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
+
+      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
+
+      def to_s
+        @message
+      end
+    end
   end
 end

data/lib/facebook/messenger/incoming.rb

@@ -5,6 +5,7 @@ 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'
 
 module Facebook
   module Messenger
@@ -17,7 +18,8 @@ module Facebook
         'postback' => Postback,
         'optin' => Optin,
         'read' => Read,
-        'account_linking' => AccountLinking
+        'account_linking' => AccountLinking,
+        'referral' => Referral
       }.freeze
 
       # Parse the given payload.

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

@@ -21,7 +21,7 @@ module Facebook
           Time.at(@messaging['timestamp'] / 1000)
         end
 
-        def type
+        def typing_on
           payload = {
             recipient: sender,
             sender_action: 'typing_on'
@@ -30,6 +30,24 @@ module Facebook
           Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
         end
 
+        def typing_off
+          payload = {
+            recipient: sender,
+            sender_action: 'typing_off'
+          }
+
+          Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
+        end
+
+        def mark_seen
+          payload = {
+            recipient: sender,
+            sender_action: 'mark_seen'
+          }
+
+          Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
+        end
+
         def reply(message)
           payload = {
             recipient: sender,

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

@@ -8,6 +8,13 @@ module Facebook
         def payload
           @messaging['postback']['payload']
         end
+
+        def referral
+          return if @messaging['postback']['referral'].nil?
+          @referral ||= Referral::Referral.new(
+            @messaging['postback']['referral']
+          )
+        end
       end
     end
   end

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

@@ -0,0 +1,39 @@
+module Facebook
+  module Messenger
+    module Incoming
+      # The Referral class represents an incoming Facebook Messenger referral.
+      #
+      # https://developers.facebook.com/docs/messenger-platform/referral-params
+      class Referral
+        include Facebook::Messenger::Incoming::Common
+
+        # The referral portion of the payload.
+        class Referral
+          def initialize(referral)
+            @referral = referral
+          end
+
+          def ref
+            @referral['ref']
+          end
+
+          def source
+            @referral['source']
+          end
+
+          def type
+            @referral['type']
+          end
+        end
+
+        def referral
+          @referral ||= Referral.new(@messaging['referral'])
+        end
+
+        def ref
+          referral.ref
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/subscriptions.rb

@@ -33,10 +33,10 @@ module Facebook
       end
 
       def raise_errors(response)
-        raise Error, response['error']['message'] if response.key? 'error'
+        raise Error, response['error'] if response.key? 'error'
       end
 
-      class Error < Facebook::Messenger::Error; end
+      class Error < Facebook::Messenger::FacebookError; end
     end
   end
 end

data/lib/facebook/messenger/thread.rb

@@ -35,7 +35,7 @@ module Facebook
       end
 
       def raise_errors(response)
-        raise Error, response['error']['message'] if response.key? 'error'
+        raise Error, response['error'] if response.key? 'error'
       end
 
       def default_options
@@ -46,7 +46,7 @@ module Facebook
         )
       end
 
-      class Error < Facebook::Messenger::Error; end
+      class Error < Facebook::Messenger::FacebookError; end
     end
   end
 end

data/lib/facebook/messenger/version.rb

@@ -1,5 +1,5 @@
 module Facebook
   module Messenger
-    VERSION = '0.11.1'.freeze
+    VERSION = '0.12.0'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: facebook-messenger
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Johannes Gorset
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-23 00:00:00.000000000 Z
+date: 2017-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -168,6 +168,8 @@ files:
 - bin/setup
 - lib/facebook/messenger.rb
 - lib/facebook/messenger/bot.rb
+- lib/facebook/messenger/bot/error_parser.rb
+- lib/facebook/messenger/bot/exceptions.rb
 - lib/facebook/messenger/configuration.rb
 - lib/facebook/messenger/configuration/providers.rb
 - lib/facebook/messenger/configuration/providers/base.rb
@@ -181,6 +183,7 @@ files:
 - lib/facebook/messenger/incoming/optin.rb
 - lib/facebook/messenger/incoming/postback.rb
 - lib/facebook/messenger/incoming/read.rb
+- lib/facebook/messenger/incoming/referral.rb
 - lib/facebook/messenger/server.rb
 - lib/facebook/messenger/subscriptions.rb
 - lib/facebook/messenger/thread.rb
@@ -205,7 +208,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Facebook Messenger client