rdstation-ruby-client 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: adcf1abef180f5dd333152cc6956191fd637f09e
-  data.tar.gz: 22ad74012fcef08e888ef1d72fb73989f84ee651
+SHA256:
+  metadata.gz: 6ade7306767c00b8d39afdeb149d4aaebe84dfd35b389e2bf1435e623dfabfb7
+  data.tar.gz: 3bdc3dc84ff1395fa65dc86e172b5ca967696e88b60bf9774723fcd33c785fbe
 SHA512:
-  metadata.gz: ad4409d04b424d90f74bab2a3d5264b7a0fe1b74b233840befff8e21a8597c40cb1cd99767292322b65a3ee309d809ad9a00ec8a851855476471fc89bb1a240c
-  data.tar.gz: 54f42eac6c63524bdacfb2c00548f3e9fdc5b0b63554c9c3ceca15f0afc24c800339506582127ebcc21b59e2b39f15ba5b3e20fe3eca9a658d0a258c9b380b5c
+  metadata.gz: fddd4b51c76c965cbd44bda5e36712f26f694fbabd59a7c0b008174cfcacd4225b73ce7640b32e9aeaed2495950ff0c19b70a555b5d8bf0dab79eaf2ce060136
+  data.tar.gz: 90d96ef3c8d917deb7adbfe0aff6e2625b7f4f1d925d6b54e806df9aa3fd3de6378358521bbfce024eb32af06695f0974ca0f0dd8b9684ed1c537f2d228c97de

data/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 2.2.0
+
+### Additions
+
+#### Configuration
+
+Now it is possible to configure global params like client_id and client_secret only once, so you don't need to provide them to `RDStation::Authentication` every time.
+
+This can be done in the following way:
+
+```ruby
+RDStation.configure do |config|
+  config.client_id = YOUR_CLIENT_ID
+  config.client_secret = YOUR_CLIENT_SECRET
+end
+```
+
+If you're using Rails, this can be done in `config/initializers`.
+
+#### Automatic refresh of access_tokens
+
+When an access_token expires, a new one will be obtained automatically and the request will be made again.
+
+For this to work, you have to use `RDStation.configure` as described above, and provide the refresh token when instantiating `RDStation::Client` (ex: RDStation::Client.new(access_token: MY_ACCESS_TOKEN, refresh_token: MY_REFRESH_TOKEN).
+
+You can keep track of access_token changes, by providing a callback block inconfiguration. This block will be called with an `RDStation::Authorization` object, which contains the updated `access_token` and `refresh_token`. For example:
+
+```ruby
+RDStation.configure do |config|
+  config.on_access_token_refresh do |authorization|
+    MyStoredAuth.where(refresh_token: authorization.refresh_token).update_all(access_token: authorization.access_token)
+  end
+end
+```
+
+### Deprecations
+
+Providing `client_id` and `client_secret` directly to `RDStation::Authentication.new` is deprecated and will be removed in future versions. Use `RDStation.configure` instead.
+
+Specifying refresh_token in `RDStation::Client.new(access_token: 'at', refresh_token: 'rt')` is optional right now, but will be mandatory in future versions. 
+
+## 2.1.1
+
+- Fixed a bug in error handling (issue [#47](https://github.com/ResultadosDigitais/rdstation-ruby-client/issues/47))
+
 ## 2.1.0
 
 ### Additions
@@ -54,6 +99,8 @@ In cause of Unahtorized (401), the following specific errors may be raised (thos
 - `RDStation::Error::ExpiredCodeGrant`
 - `RDStation::Error::InvalidCredentials`
 
+The specific message and the http code are now returned by the `details` method.
+
 ### Dependencies
 
 `rdstation-ruby-client` now requires `ruby >= 2.0.0`.

data/README.md

@@ -10,12 +10,13 @@ Upgrading? Check the [migration guide](#Migration-guide) before bumping to a new
 
 1. [Installation](#Installation)
 2. [Usage](#Usage)
-   1. [Authentication](#Authentication)
-   2. [Contacts](#Contacts)
-   3. [Events](#Events)
-   4. [Fields](#Fields)
-   5. [Webhooks](#Webhooks)
-   6. [Errors](#Errors)
+   1. [Configuration](#Configuration)
+   2. [Authentication](#Authentication)
+   3. [Contacts](#Contacts)
+   4. [Events](#Events)
+   5. [Fields](#Fields)
+   6. [Webhooks](#Webhooks)
+   7. [Errors](#Errors)
 3. [Changelog](#Changelog)
 4. [Migration guide](#Migration-guide)
    1. [Upgrading from 1.2.x to 2.0.0](#Upgrading-from-1.2.x-to-2.0.0)
@@ -39,6 +40,19 @@ Or install it yourself as:
 
 ## Usage
 
+### Configuration
+
+Before getting youre credentials, you need to configure client_id and client_secret as following:
+
+```ruby
+RDStation.configure do |config|
+  config.client_id = YOUR_CLIENT_ID
+  config.client_secret = YOUR_CLIENT_SECRET
+end
+```
+
+For details on what `client_id` and `client_secret` are, check the [developers portal](https://developers.rdstation.com/en/authentication).
+
 ### Authentication
 
 For more details, check the [developers portal](https://developers.rdstation.com/en/authentication).
@@ -46,7 +60,7 @@ For more details, check the [developers portal](https://developers.rdstation.com
 #### Getting authentication URL
 
 ```ruby
-rdstation_authentication = RDStation::Authentication.new('client_id', 'client_secret')
+rdstation_authentication = RDStation::Authentication.new
 
 redirect_url = 'https://yourapp.org/auth/callback'
 rdstation_authentication.auth_url(redirect_url)
@@ -57,17 +71,35 @@ rdstation_authentication.auth_url(redirect_url)
 You will need the code param that is returned from RD Station to your application after the user confirms the access at the authorization dialog.
 
 ```ruby
-rdstation_authentication = RDStation::Authentication.new('client_id', 'client_secret')
+rdstation_authentication = RDStation::Authentication.new
 rdstation_authentication.authenticate(code_returned_from_rdstation)
+# => { 'access_token' => '54321', 'expires_in' => 86_400, 'refresh_token' => 'refresh' }
 ```
 
-#### Updating access_token
+#### Updating an expired access_token
 
 ```ruby
-rdstation_authentication = RDStation::Authentication.new('client_id', 'client_secret')
+rdstation_authentication = RDStation::Authentication.new
 rdstation_authentication.update_access_token('refresh_token')
 ```
 
+**NOTE**: This is done automatically when a request fails due to access_token expiration. To keep track of the new token, you have to provide a callback block in configuration. For example:
+
+```ruby
+RDStation.configure do |config|
+  config.client_id = YOUR_CLIENT_ID
+  config.client_secret = YOUR_CLIENT_SECRET
+  config.on_access_token_refresh do |authorization|
+    # authorization.access_token_expires_in is the time (in seconds for with the token is valid)
+    # authorization.access_token is the new token
+    # authorization.refresh_token is the existing refresh_token
+    # 
+    # If you are using ActiveRecord, you may want to update the stored access_token, like in the following code:
+    MyStoredAuth.where(refresh_token: authorization.refresh_token).update_all(access_token: authorization.access_token)
+  end
+end
+```
+
 #### Revoking an access_token
 
 ```ruby
@@ -83,7 +115,7 @@ Note: this will completely remove your credentials from RD Station (`update_acce
 Returns data about a specific Contact
 
 ```ruby
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.contacts.by_uuid('uuid')
 ```
 
@@ -94,7 +126,7 @@ More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDe
 Returns data about a specific Contact
 
 ```ruby
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.contacts.by_email('email')
 ```
 
@@ -109,7 +141,7 @@ contact_info = {
   name: "Joe Foo"
 }
 
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.contacts.update('uuid', contact_info)
 ```
 Contact Default Parameters
@@ -139,7 +171,7 @@ contact_info = {
 identifier = "email"
 identifier_value = "joe@foo.bar"
 
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.contacts.upsert(identifier, identifier_value, contact_info)
 ```
 
@@ -159,7 +191,7 @@ This creates a new event on RDSM:
 
 ```ruby
 payload = {} # hash representing the payload
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.events.create(payload)
 ```
 
@@ -170,7 +202,7 @@ Endpoints to [manage Contact Fields](https://developers.rdstation.com/en/referen
 #### List all fields
 
 ```ruby
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.fields.all
 ```
 
@@ -183,14 +215,14 @@ Choose to receive data based on certain actions, re-cast or marked as an opportu
 #### List all webhooks
 
 ```ruby
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.webhooks.all
 ```
 
 #### Getting a webhook by UUID
 
 ```ruby
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.webhooks.by_uuid('WEBHOOK_UUID')
 ```
 
@@ -198,7 +230,7 @@ client.webhooks.by_uuid('WEBHOOK_UUID')
 
 ```ruby
 payload = {} # payload representing a webhook
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.webhooks.create(payload)
 ```
 
@@ -208,7 +240,7 @@ The required strucutre of the payload is [described here](https://developers.rds
 
 ```ruby
 payload = {} # payload representing a webhook
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.webhooks.create('WEBHOOK_UUID', payload)
 ```
 
@@ -217,7 +249,7 @@ The required strucutre of the payload is [described here](https://developers.rds
 #### Deleting a webhook
 
 ```ruby
-client = RDStation::Client.new(access_token: 'access_token')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
 client.webhooks.delete('WEBHOOK_UUID')
 ```
 
@@ -249,6 +281,8 @@ In cause of Unauthorized (401), the following specific errors may be raised (tho
 - `RDStation::Error::ExpiredCodeGrant`
 - `RDStation::Error::InvalidCredentials`
 
+Any error class has a `details` method which returns the specific error message and the http_status.
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md)
@@ -263,7 +297,7 @@ So, here is a step-by-step guide on how to upgrade your app:
 - Ensure you're using `ruby >= 2.0.0`.
 - Remove every direct instantiation of `RDStation::Contacts`, `RDStation::Events`, `RDStation::Fields` and `RDStation::Webhooks` and use `RDStation::Client` to get them instead.
 - Replace any call of `RDStation::Client#create_lead`, `RDStation::Client#change_lead` or `RDStation::Client#change_lead_status` with the equivalent method in the [Contacts API](#Contacts).
-- Review your error handling, as [more options](CHANGELOG.md#Error-handling) are available now.
+- Review your error handling, as [more options](CHANGELOG.md#Error-handling) are available now. `http_status` method will always return nil. To get the status now use `error.details[:http_status]` or check the type of the class.
 
 ## Contributing
 

data/lib/rdstation-ruby-client.rb

@@ -4,8 +4,10 @@ require 'httparty'
 require 'rdstation/api_response'
 
 # API requests
+require 'rdstation'
+require 'rdstation/retryable_request'
 require 'rdstation/authentication'
-require 'rdstation/authorization_header'
+require 'rdstation/authorization'
 require 'rdstation/client'
 require 'rdstation/contacts'
 require 'rdstation/events'

data/lib/rdstation.rb

@@ -0,0 +1,19 @@
+module RDStation
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+  end
+  
+  class Configuration
+    attr_accessor :client_id, :client_secret
+    attr_reader :access_token_refresh_callback
+
+    def on_access_token_refresh(&block)
+      @access_token_refresh_callback = block
+    end
+  end
+end

data/lib/rdstation/api_response.rb

@@ -1,8 +1,7 @@
 module RDStation
   module ApiResponse
     def self.build(response)
-      response_body = JSON.parse(response.body)
-      return response_body if response.code.between?(200, 299)
+      return JSON.parse(response.body) if response.code.between?(200, 299)
 
       RDStation::ErrorHandler.new(response).raise_error
     end

data/lib/rdstation/authentication.rb

@@ -7,9 +7,10 @@ module RDStation
     DEFAULT_HEADERS = { 'Content-Type' => 'application/json' }.freeze
     REVOKE_URL = 'https://api.rd.services/auth/revoke'.freeze
 
-    def initialize(client_id, client_secret)
-      @client_id = client_id
-      @client_secret = client_secret
+    def initialize(client_id = nil, client_secret = nil)
+      warn_deprecation if client_id || client_secret
+      @client_id = client_id || RDStation.configuration&.client_id
+      @client_secret = client_secret || RDStation.configuration&.client_secret
     end
 
     #
@@ -83,5 +84,9 @@ module RDStation
         headers: DEFAULT_HEADERS
       )
     end
+
+    def warn_deprecation
+      warn "DEPRECATION WARNING: Providing client_id and client_secret directly to RDStation::Authentication.new is deprecated and will be removed in future versions. Use RDStation.configure instead."
+    end
   end
 end

data/lib/rdstation/{authorization_header.rb → authorization.rb}

@@ -1,21 +1,24 @@
 module RDStation
-  class AuthorizationHeader
-    
-    def initialize(access_token:)
+  class Authorization
+    attr_reader :refresh_token
+    attr_accessor :access_token, :access_token_expires_in
+    def initialize(access_token:, refresh_token: nil, access_token_expires_in: nil)
       @access_token = access_token
+      @refresh_token = refresh_token
+      @access_token_expires_in = access_token_expires_in
       validate_access_token access_token
     end
-    
-    def to_h
+
+    def headers
       { "Authorization" => "Bearer #{@access_token}", "Content-Type" => "application/json" }
     end
-    
+
     private
-    
+
     def validate_access_token(access_token)
       access_token_msg = ':access_token is required'
       raise ArgumentError, access_token_msg unless access_token
     end
-    
+
   end
 end

data/lib/rdstation/client.rb

@@ -1,23 +1,33 @@
 module RDStation
   class Client
-    def initialize(access_token:)
-      @authorization_header = AuthorizationHeader.new(access_token: access_token)
+    def initialize(access_token:, refresh_token: nil)
+      warn_deprecation unless refresh_token
+      @authorization = Authorization.new(
+        access_token: access_token,
+        refresh_token: refresh_token
+      )
     end
-    
+
     def contacts
-      @contacts ||= RDStation::Contacts.new(authorization_header: @authorization_header)
+      @contacts ||= RDStation::Contacts.new(authorization: @authorization)
     end
 
     def events
-      @events ||= RDStation::Events.new(authorization_header: @authorization_header)
+      @events ||= RDStation::Events.new(authorization: @authorization)
     end
 
     def fields
-      @fields ||= RDStation::Fields.new(authorization_header: @authorization_header)
+      @fields ||= RDStation::Fields.new(authorization: @authorization)
     end
 
     def webhooks
-      @webhooks ||= RDStation::Webhooks.new(authorization_header: @authorization_header)
+      @webhooks ||= RDStation::Webhooks.new(authorization: @authorization)
+    end
+
+    private
+
+    def warn_deprecation
+      warn "DEPRECATION WARNING: Specifying refresh_token in RDStation::Client.new(access_token: 'at', refresh_token: 'rt') is optional right now, but will be mandatory in future versions. "
     end
   end
 end

data/lib/rdstation/contacts.rb

@@ -3,9 +3,10 @@ module RDStation
   # More info: https://developers.rdstation.com/pt-BR/reference/contacts
   class Contacts
     include HTTParty
-    
-    def initialize(authorization_header:)
-      @authorization_header = authorization_header
+    include ::RDStation::RetryableRequest
+
+    def initialize(authorization:)
+      @authorization = authorization
     end
 
     #
@@ -13,13 +14,17 @@ module RDStation
     #   The unique uuid associated to each RD Station Contact.
     #
     def by_uuid(uuid)
-      response = self.class.get(base_url(uuid), headers: @authorization_header.to_h)
-      ApiResponse.build(response)
+      retryable_request(@authorization) do |authorization|
+        response = self.class.get(base_url(uuid), headers: authorization.headers)
+        ApiResponse.build(response)
+      end
     end
 
     def by_email(email)
-      response = self.class.get(base_url("email:#{email}"), headers: @authorization_header.to_h)
-      ApiResponse.build(response)
+      retryable_request(@authorization) do |authorization|
+        response = self.class.get(base_url("email:#{email}"), headers: authorization.headers)
+        ApiResponse.build(response)
+      end
     end
 
     # The Contact hash may contain the following parameters:
@@ -34,8 +39,10 @@ module RDStation
     # :website
     # :tags
     def update(uuid, contact_hash)
-      response = self.class.patch(base_url(uuid), :body => contact_hash.to_json, :headers => @authorization_header.to_h)
-      ApiResponse.build(response)
+      retryable_request(@authorization) do |authorization|
+        response = self.class.patch(base_url(uuid), :body => contact_hash.to_json, :headers => authorization.headers)
+        ApiResponse.build(response)
+      end
     end
 
     #
@@ -47,14 +54,16 @@ module RDStation
     #   Contact data
     #
     def upsert(identifier, identifier_value, contact_hash)
-      path = "#{identifier}:#{identifier_value}"
-      response = self.class.patch(base_url(path), body: contact_hash.to_json, headers: @authorization_header.to_h)
-      ApiResponse.build(response)
+      retryable_request(@authorization) do |authorization|
+        path = "#{identifier}:#{identifier_value}"
+        response = self.class.patch(base_url(path), body: contact_hash.to_json, headers: authorization.headers)
+        ApiResponse.build(response)
+      end
     end
 
     private
 
-    def base_url(path = "")
+    def base_url(path = '')
       "https://api.rd.services/platform/contacts/#{path}"
     end
   end