rdstation-ruby-client 2.1.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: adcf1abef180f5dd333152cc6956191fd637f09e
-  data.tar.gz: 22ad74012fcef08e888ef1d72fb73989f84ee651
+SHA256:
+  metadata.gz: 5df3763feda5bcb841946b403695b54933c0fcc9b0b9da1c907146454e5311ff
+  data.tar.gz: 63cd80564336415bc361c3dfce276611d1b1a6b61c68554e4f1a212c73fd9c7e
 SHA512:
-  metadata.gz: ad4409d04b424d90f74bab2a3d5264b7a0fe1b74b233840befff8e21a8597c40cb1cd99767292322b65a3ee309d809ad9a00ec8a851855476471fc89bb1a240c
-  data.tar.gz: 54f42eac6c63524bdacfb2c00548f3e9fdc5b0b63554c9c3ceca15f0afc24c800339506582127ebcc21b59e2b39f15ba5b3e20fe3eca9a658d0a258c9b380b5c
+  metadata.gz: 60eded16372c0d970d67b5f456a28d8adb9e7f013f8551e56b72598752ea9a0c24f99fdf4f3c943f040872d71a837279d769b43ac7b2e36d2c0c5eaa8ae9f405
+  data.tar.gz: 1107d1405d1984cd36de905403f3a53a6275505e55ff4c4d5661f7914d268f11031d81c5602464ca2f573b61831d5516a437abe9501a1fd8a34549ec3a36753f

data/CHANGELOG.md

@@ -1,3 +1,121 @@
+## 2.5.0
+
+- InvalidRefreshToken error added. This error will be raised when the refresh token is invalid or it was revoked. When you get this error, you can safely disconnect the user from RD Station.
+
+Usage example:
+
+```ruby
+begin
+  rdstation.update_access_token(refresh_token)
+rescue RDStation::Error::InvalidRefreshToken
+  # Disconnect user
+end
+```
+
+## 2.4.0
+
+- Add the TooManyRequests errors in case of rate limit exceeded. See [API request limit](https://developers.rdstation.com/en/request-limit) for more details
+
+## 2.3.1
+
+- Fixed a bug when no error is found in the known errors list (issue [#52](https://github.com/ResultadosDigitais/rdstation-ruby-client/issues/52))
+
+## 2.3.0
+
+### Additions
+
+#### 1. New Field methods
+
+The following methods were added to "Fields" client:
+
+- create
+- update
+- delete
+
+Besides reading, this client is now capable of create, update or delete a field.
+
+Usage example:
+
+```ruby
+client = RDStation::Client.new(access_token: 'ACCESS_TOKEN', refresh_token: 'REFRESH_TOKEN')
+client.fields.delete('FIELD_UUID')
+```
+
+#### 2. New format of errors supported
+
+Two new formats of errors are now supported by the error handler:
+
+##### `HASH_OF_HASHES`
+
+When the error message is a hash containing other hashes as values, for example:
+
+```ruby
+{
+  'error' => {
+    'field1' => {...},
+    'field2' => {...}
+  }
+}
+```
+
+##### `HASH_OF_MULTIPLE_TYPES`
+
+When the error message is a hash that could contain multiple data types as values, for example:
+
+```ruby
+{
+  'error' => {
+    'field1' => [...] # Array,
+    'field2' => {...} # Hash
+  }
+}
+```
+
+## 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
@@ -49,11 +167,13 @@ In case of a Bad Request (400), the following specific errors may be raised (tho
 - `RDStation::Error::ConflictingField`
 - `RDStation::Error::InvalidEventType`
 
-In cause of Unahtorized (401), the following specific errors may be raised (those are subclasses of `RDStation::Error::Unauthorized`):
+In cause of Unauthorized (401), the following specific errors may be raised (those are subclasses of `RDStation::Error::Unauthorized`):
 - `RDStation::Error::ExpiredAccessToken`
 - `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,10 +202,59 @@ 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
 ```
 
+#### Create a field
+
+```ruby
+payload = {} # hash representing the payload
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.fields.create payload
+```
+Or you can use the new `RDStation::Builder::Field`
+
+```ruby
+payload = {} # hash representing the payload
+builder = RDStation::Builder::Field.new payload['api_identifier']
+builder.data_type(payload['data_type'])
+builder.presentation_type(payload['presentation_type'])
+builder.name('pt-BR', payload['name'])
+builder.label('pt-BR', payload['label'])
+
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.fields.create builder.build
+```
+
+#### Update a field
+
+```ruby
+payload = {} # hash representing the payload
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.fields.update('FIELD_UUID', payload)
+```
+Or you can use the new `RDStation::Builder::Field`
+
+```ruby
+payload = {} # hash representing the payload
+builder = RDStation::Builder::Field.new payload['api_identifier']
+builder.data_type(payload['data_type'])
+builder.presentation_type(payload['presentation_type'])
+builder.name('pt-BR', payload['name'])
+builder.label('pt-BR', payload['label'])
+
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.fields.update('FIELD_UUID', builder.build)
+```
+#### Deleting a field
+
+```ruby
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.fields.delete('FIELD_UUID')
+```
+
+
 ### Webhooks
 
 Webhooks provide the ability to receive real-time data updates about your contact activity.
@@ -183,14 +264,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 +279,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 +289,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 +298,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')
 ```
 
@@ -234,6 +315,7 @@ Each endpoint may raise errors accoording to the HTTP response code from RDStati
 - `RDStation::Error::Conflict` (409)
 - `RDStation::Error::UnsupportedMediaType` (415)
 - `RDStation::Error::UnprocessableEntity` (422)
+- `RDStation::Error::TooManyRequests` (429)
 - `RDStation::Error::InternalServerError` (500)
 - `RDStation::Error::NotImplemented` (501)
 - `RDStation::Error::BadGateway` (502)
@@ -249,6 +331,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 +347,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/Rakefile

@@ -5,3 +5,7 @@ RSpec::Core::RakeTask.new
 
 task :default => :spec
 task :test => :spec
+
+task :console do
+  exec 'pry -r rdstation-ruby-client -I ./lib'
+end

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'
@@ -15,3 +17,6 @@ require 'rdstation/webhooks'
 # Error handling
 require 'rdstation/error'
 require 'rdstation/error_handler'
+
+# Builders
+require 'rdstation/builder/field'

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