rdstation-ruby-client 1.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a0928853bb9ae75ec8ed56f8f532c18ddc42c205
-  data.tar.gz: 74e5de6ea1c9f33cae06f781f4979a0e674b7e1b
+SHA256:
+  metadata.gz: 93cdc7036300cb21cf4609bb92042f47e280a864f84cfaba3b5a9e6181274aad
+  data.tar.gz: 349d48fb5a969953c3e637b0cf73aef037328aafff3aeb779c7f217c0ac1e537
 SHA512:
-  metadata.gz: a89281c0b92792ebe57eb4383dcb460aa0edc04b967a8aa283a7272fc336dd410ba4b2e0482109949cb6f27321af5566c055bd49c9e7a55efa85c995b4329ab4
-  data.tar.gz: 0703a456fd3772fa02b1026f69c6bcec1b3dfb22b34efe93ba6ce75c4bcd528feb88b2d9dba8dc97d4dccc14eaa8c9a965c59367bc0e786106b57f1e2c3f9271
+  metadata.gz: 8cfa5e1cd4d75f9a30536b99055075e92a7bdb3630ed8b71cfc66f4032983677079d78663d9eaadc4fcfb88875665281e271b270c6a584e93a81b5065bd7f005
+  data.tar.gz: 7e64c0b2983ce2d081d4236c42d432a7c994f2927f17e766020067b512a2ed47b1988acdc5c1a8d81edaf3cd0acc43f96209e1a0192abb11d0f52074758a1989

data/.github/ISSUE_TEMPLATE/rdsm-ruby-client-issue-template.md

@@ -0,0 +1,49 @@
+---
+name: RDSM Ruby Client Issue Template
+about: Template for new Issues for the RD Station Ruby Client Project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+# Prerequisites
+
+Please answer the following questions for yourself before submitting an issue. **YOU MAY DELETE THE PREREQUISITES SECTION.**
+
+- [ ] I am running the latest version
+- [ ] I checked the documentation and found no answer
+- [ ] I checked to make sure that this issue has not already been filed
+- [ ] I'm reporting the issue to the correct repository
+
+# Expected Behavior
+
+Please describe the behavior you are expecting
+
+# Current Behavior
+
+What is the current behavior?
+
+# Failure Information (for bugs)
+
+Please help to provide information about the failure if this is a bug. If it is not a bug, please remove the rest of this template.
+
+## Steps to Reproduce
+
+Please provide detailed steps for reproducing the issue.
+
+1. step 1
+2. step 2
+3. you get it...
+
+## Context
+
+Please provide any relevant information about your setup. This is important in case the issue is not reproducible except for under certain conditions.
+
+* Operating System:
+* Ruby Version:
+* Rails Version:
+
+## Failure Logs
+
+Please include any relevant log snippets or files here.

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--order rand

data/CHANGELOG.md

@@ -0,0 +1,163 @@
+## 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 [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
+
+#### RDStation::Client
+
+Now `RDStation::Client` is facade to all available endpoints in the 2.0 API. It needs to be instantiated with an access_token and has accessors to those endpoints. Usage examples:
+
+```ruby
+  client = RDStation::Client.new((access_token: 'my_token')
+  client.contacts.by_uuid('CONTACT_UUID')
+  client.webhooks.all
+  client.events.create(my_json_payload)
+  client.fields.all
+```
+
+`RDStation::Contacts`, `RDStation::Events`, `RDStation::Fields` and `RDStation::Webhooks` are not suposed to be instantiated directly anymore. Use `RDStation::Client` to get them instead.
+
+#### Error handling
+
+Now specific errors are raised for each HTTP status:
+
+- `RDStation::Error::BadRequest` (400)
+- `RDStation::Error::Unauthorized` (401)
+- `RDStation::Error::Forbidden` (403)
+- `RDStation::Error::NotFound` (404)
+- `RDStation::Error::MethodNotAllowed` (405)
+- `RDStation::Error::NotAcceptable` (406)
+- `RDStation::Error::Conflict` (409)
+- `RDStation::Error::UnsupportedMediaType` (415)
+- `RDStation::Error::UnprocessableEntity` (422)
+- `RDStation::Error::InternalServerError` (500)
+- `RDStation::Error::NotImplemented` (501)
+- `RDStation::Error::BadGateway` (502)
+- `RDStation::Error::ServiceUnavailable` (503)
+- `RDStation::Error::ServerError` (which is returned for 5xx errors different than 500, 501, 502 or 503)
+
+In case of a Bad Request (400), the following specific errors may be raised (those are subclasses of `RDStation::Error::BadRequest`):
+- `RDStation::Error::ConflictingField`
+- `RDStation::Error::InvalidEventType`
+
+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
+
+### 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.

data/README.md

@@ -4,6 +4,26 @@
 
 RDstation ruby wrapper to interact with RDStation API.
 
+Upgrading? Check the [migration guide](#Migration-guide) before bumping to a new major version.
+
+## Table of Contents
+
+1. [Installation](#Installation)
+2. [Usage](#Usage)
+   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)
+5. [Contributing](#Contributing)
+6. [Maintainers](#Maintainers)
+7. [Reference](#Reference)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,41 +40,27 @@ Or install it yourself as:
 
 ## Usage
 
-### Creating a Lead
-
-```ruby
-lead_info = {
-  email: 'joe@foo.bar',
-  name: 'Joe foo',
-  empresa: 'A random Company',
-  cargo: 'Developer',
-  identificador: 'nome_da_conversao'
-}
-
-rdstation_client = RDStation::Client.new('rdstation_token', 'auth_token')
-rdstation_client.create_lead(lead_info)
-```
+### Configuration
 
-### Changing a Lead
+Before getting youre credentials, you need to configure client_id and client_secret as following:
 
 ```ruby
-rdstation_client = RDStation::Client.new('rdstation_token', 'auth_token')
-rdstation_client.change_lead('joe@foo.bar', lifecycle_stage: 1, opportunity: true})
+RDStation.configure do |config|
+  config.client_id = YOUR_CLIENT_ID
+  config.client_secret = YOUR_CLIENT_SECRET
+end
 ```
 
-### Change Lead Status
-
-```ruby
-rdstation_client = RDStation::Client.new('rdstation_token', 'auth_token')
-rdstation_client.change_lead_status(email: 'joe@foo.bar', status: 'won', value: 999)
-```
+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).
+
 #### 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)
@@ -65,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
@@ -83,8 +115,8 @@ rdstation_authentication.update_access_token('refresh_token')
 Returns data about a specific Contact
 
 ```ruby
-contact = RDStation::Contacts.new('auth_token')
-contact.by_uuid('uuid')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.by_uuid('uuid')
 ```
 
 More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDetailsuuid
@@ -94,8 +126,8 @@ More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDe
 Returns data about a specific Contact
 
 ```ruby
-contact = RDStation::Contacts.new('auth_token')
-contact.by_email('email')
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.by_email('email')
 ```
 
 More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDetailsemail
@@ -109,8 +141,8 @@ contact_info = {
   name: "Joe Foo"
 }
 
-contact = RDStation::Contacts.new('auth_token')
-contact.update('uuid', contact_info)
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.update('uuid', contact_info)
 ```
 Contact Default Parameters
  - email
@@ -139,12 +171,183 @@ contact_info = {
 identifier = "email"
 identifier_value = "joe@foo.bar"
 
-contact = RDStation::Contacts.new('auth_token')
-contact.upsert(identifier, identifier_value, contact_info)
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.upsert(identifier, identifier_value, contact_info)
 ```
 
 More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodPatchUpsertDetails
 
+### Events
+
+#### Sending a new event
+
+The events endpoint are responsible for receiving different event types in which RD Station Contacts take part in.
+
+It is possible to send default events to RD Station such as conversion events, lifecycle events and won and lost events. Also, RD Station supports the possibility of receiving different event types, for instance, chat events, ecommerce ones and others.
+
+Check the [developers portal](https://developers.rdstation.com/en/reference/events) to learn about the required payload structure and which events are available.
+
+This creates a new event on RDSM:
+
+```ruby
+payload = {} # hash representing the payload
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.events.create(payload)
+```
+
+### Fields
+
+Endpoints to [manage Contact Fields](https://developers.rdstation.com/en/reference/fields) information in your RD Station account.
+
+#### List all fields
+
+```ruby
+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.
+
+Choose to receive data based on certain actions, re-cast or marked as an opportunity, and have all applicable data sent to a URL of your choice. You can then use your own custom application to read, save, and do actions with that data. This is a powerful option that allows you to keep all your data in sync and opens the possibility for all types of integration.
+
+#### List all webhooks
+
+```ruby
+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', refresh_token: 'refresh_token')
+client.webhooks.by_uuid('WEBHOOK_UUID')
+```
+
+#### Creating a webhook
+
+```ruby
+payload = {} # payload representing a webhook
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.webhooks.create(payload)
+```
+
+The required strucutre of the payload is [described here](https://developers.rdstation.com/en/reference/webhooks#methodPostDetails).
+
+#### Updating a webhook
+
+```ruby
+payload = {} # payload representing a webhook
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.webhooks.create('WEBHOOK_UUID', payload)
+```
+
+The required strucutre of the payload is [described here](https://developers.rdstation.com/en/reference/webhooks#methodPutDetails).
+
+#### Deleting a webhook
+
+```ruby
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.webhooks.delete('WEBHOOK_UUID')
+```
+
+### Errors
+
+Each endpoint may raise errors accoording to the HTTP response code from RDStation:
+
+- `RDStation::Error::BadRequest` (400)
+- `RDStation::Error::Unauthorized` (401)
+- `RDStation::Error::Forbidden` (403)
+- `RDStation::Error::NotFound` (404)
+- `RDStation::Error::MethodNotAllowed` (405)
+- `RDStation::Error::NotAcceptable` (406)
+- `RDStation::Error::Conflict` (409)
+- `RDStation::Error::UnsupportedMediaType` (415)
+- `RDStation::Error::UnprocessableEntity` (422)
+- `RDStation::Error::InternalServerError` (500)
+- `RDStation::Error::NotImplemented` (501)
+- `RDStation::Error::BadGateway` (502)
+- `RDStation::Error::ServiceUnavailable` (503)
+- `RDStation::Error::ServerError` (which is returned for 5xx errors different than 500, 501, 502 or 503)
+
+In case of a Bad Request (400), the following specific errors may be raised (those are subclasses of `RDStation::Error::BadRequest`):
+- `RDStation::Error::ConflictingField`
+- `RDStation::Error::InvalidEventType`
+
+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`
+
+Any error class has a `details` method which returns the specific error message and the http_status.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md)
+
+## Migration guide
+
+### Upgrading from 1.2.x to 2.0.0
+
+v2.0.0 main change is that it drops support for RDSM's old 1.x API. If you're not familiar with the 2.0 API yet, [check it out](https://developers.rdstation.com) first. Also take a look at [the release notes](CHANGELOG.md#2.0.0), as they explain the changes in greater detail.
+
+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. `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
 
 1. Fork it
@@ -153,14 +356,11 @@ More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodPatch
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
-## Maintainer
-[Nando Sousa](mailto:fernando.sousa@resultadosdigitais.com.br)
+## Maintainers
 
-## Reference
+- [Filipe Nascimento](mailto:filipe.nascimento@resultadosdigitais.com.br)
+- [João Hornburg](mailto:joao@rdstation.com)
 
-You can check out RDstation's integration (pt-BR) documentation here:
+## Reference
 
-- [Pure HTML](https://gist.github.com/pedrobachiega/3298970);
-- [Wordpress & Contact Form 7](https://gist.github.com/pedrobachiega/3277536);
-- [PHP](https://gist.github.com/pedrobachiega/3248293);
-- [HTML+Ajax with jQuery](https://gist.github.com/pedrobachiega/3248013);
+You can check out RDstation's integration documentation at our [developers portal](https://developers.rdstation.com).