rdstation-ruby-client 2.0.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ca94a755162557e5fcca58d15583986492ee1ef64c569c54d7c8a6feab6edec
-  data.tar.gz: 7b258da27dd4f13148e2f9de60a4a95eb32131fb0e5e0d8f5cc133eb3e4720fd
+  metadata.gz: d51df272057d17abe280b0fe23f7a97f9ef2ceb543f823db1ce8b047788d1887
+  data.tar.gz: d59bd8063663bb95df477c672066e4c6655172a193d9b2244bba6b8608a92869
 SHA512:
-  metadata.gz: 28bf2fc07e73df574917d1b441867146d3120d44a7e72599399648b118922c04c7e4fc75364180bdc175c14ee77c2452cf7ff02885d83d7daf6924c642876759
-  data.tar.gz: c70a26f5d2b8a42d6b4deb8ee3de27ad817262e58b033a88200bcda04f9c36e468f2ce919b25d29181d810eb286a018a8eaed52eb04e4f545682e7a36b7a3876
+  metadata.gz: 1451abf2db818f4551575ea88befdb63b6f8f8b1afa3270b96ee50b059f0f69676d6c6104a6e217d58e9c84384527d77e81d257d5a222a1ab2df74e1ed525446
+  data.tar.gz: 06c2620cdf413e945207f7b0bad15bcdb762038b360ef3c9ed5371e2ff06edc4949f97602fc0c3ffc352ff14bf66774234c398b291a5606d34931ab0eded84e9

data/CHANGELOG.md

@@ -1,8 +1,118 @@
+## 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
+
+`RDStation::Authentication.revoke`  added. This method revokes an access_token at RD Station.
+
 ## 2.0.0
 
 ### Removals
 
-All API methods that were called directly on `RDStation::Client` (ex: `RDStation::Client.new('rdstation_token', 'auth_token').create_lead(lead_info)`) have been removed. See the [upgrading guide](#Upgrading-to-version-2.0.0) for a comprehensive guide on how to upgrade from version 1.2.x.
+All API methods that were called directly on `RDStation::Client` (ex: `RDStation::Client.new('rdstation_token', 'auth_token').create_lead(lead_info)`) have been removed. See the [migration guide](README.md#Upgrading-from-1.2.x-to-2.0.0) for a comprehensive guide on how to upgrade from version 1.2.x.
 
 ### Notable changes
 
@@ -43,17 +153,19 @@ 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`.
 
-## 1.2.1 
+## 1.2.1
 
 ### Deprecations
 
-All API methods that were called directly on `RDStation::Client` (ex: `RDStation::Client.new('rdstation_token', 'auth_token').create_lead(lead_info)`) are now deprecated. Those methods call RDSM's 1.3 API and will be removed in the next release.
+All API methods that were called directly on `RDStation::Client` (ex: `RDStation::Client.new('rdstation_token', 'auth_token').create_lead(lead_info)`) are now deprecated. Those methods call RDSM's 1.3 API and will be removed in the next release.

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,43 @@ 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
+RDStation::Authentication.revoke(access_token: "your token")
+```
+
+Note: this will completely remove your credentials from RD Station (`update_access_token` won't work anymore).
+
 ### Contacts
 
 #### Getting a Contact by UUID
@@ -75,7 +115,7 @@ rdstation_authentication.update_access_token('refresh_token')
 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')
 ```
 
@@ -86,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')
 ```
 
@@ -101,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
@@ -131,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)
 ```
 
@@ -151,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)
 ```
 
@@ -162,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.
@@ -175,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')
 ```
 
@@ -190,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)
 ```
 
@@ -200,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)
 ```
 
@@ -209,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')
 ```
 
@@ -226,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)
@@ -241,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)
@@ -255,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/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