rdstation-ruby-client 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b061b8a4742fb7cff52c977a633fb91b31f9b59021ed13cb249323233f5e1a1
-  data.tar.gz: f3ea76482500d4042ad946112d547aea3cfc34514ea1539e5aacddce8d1a93d9
+  metadata.gz: 5ca94a755162557e5fcca58d15583986492ee1ef64c569c54d7c8a6feab6edec
+  data.tar.gz: 7b258da27dd4f13148e2f9de60a4a95eb32131fb0e5e0d8f5cc133eb3e4720fd
 SHA512:
-  metadata.gz: 85b617237d11e956886ce1388cdfd892c5e8eeb961597551e0499cfafc63bb0f5cad18ce817d7c921f50436cb7f2a217a8f2662804432829bed7fa0f862eecdf
-  data.tar.gz: 714d715427d726adf4438782db176a5301bf299df02346ad9fd911f955f2f3fef5a9fe884ee476d7f2fa56bdb266dfa6f7b2fce6602692ee00b5ded2a0ed03a4
+  metadata.gz: 28bf2fc07e73df574917d1b441867146d3120d44a7e72599399648b118922c04c7e4fc75364180bdc175c14ee77c2452cf7ff02885d83d7daf6924c642876759
+  data.tar.gz: c70a26f5d2b8a42d6b4deb8ee3de27ad817262e58b033a88200bcda04f9c36e468f2ce919b25d29181d810eb286a018a8eaed52eb04e4f545682e7a36b7a3876

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,59 @@
+## 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.
+
+### 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 Unahtorized (401), the following specific errors may be raised (those are subclasses of `RDStation::Error::Unauthorized`):
+- `RDStation::Error::ExpiredAccessToken`
+- `RDStation::Error::ExpiredCodeGrant`
+- `RDStation::Error::InvalidCredentials`
+
+### 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,25 @@
 
 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. [Authentication](#Authentication)
+   2. [Contacts](#Contacts)
+   3. [Events](#Events)
+   4. [Fields](#Fields)
+   5. [Webhooks](#Webhooks)
+   6. [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,37 +39,10 @@ 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)
-```
-
-### Changing a Lead
-
-```ruby
-rdstation_client = RDStation::Client.new('rdstation_token', 'auth_token')
-rdstation_client.change_lead('joe@foo.bar', lifecycle_stage: 1, opportunity: true})
-```
-
-### 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)
-```
-
 ### Authentication
 
+For more details, check the [developers portal](https://developers.rdstation.com/en/authentication).
+
 #### Getting authentication URL
 
 ```ruby
@@ -83,8 +75,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')
+client.contacts.by_uuid('uuid')
 ```
 
 More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDetailsuuid
@@ -94,8 +86,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')
+client.contacts.by_email('email')
 ```
 
 More info: https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDetailsemail
@@ -109,8 +101,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')
+client.contacts.update('uuid', contact_info)
 ```
 Contact Default Parameters
  - email
@@ -139,12 +131,132 @@ 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')
+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')
+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')
+client.fields.all
+```
+
+### 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')
+client.webhooks.all
+```
+
+#### Getting a webhook by UUID
+
+```ruby
+client = RDStation::Client.new(access_token: 'access_token')
+client.webhooks.by_uuid('WEBHOOK_UUID')
+```
+
+#### Creating a webhook
+
+```ruby
+payload = {} # payload representing a webhook
+client = RDStation::Client.new(access_token: 'access_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')
+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')
+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`
+
+## 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.
+
 ## Contributing
 
 1. Fork it
@@ -153,14 +265,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).

data/lib/rdstation-ruby-client.rb

@@ -5,6 +5,7 @@ require 'rdstation/api_response'
 
 # API requests
 require 'rdstation/authentication'
+require 'rdstation/authorization_header'
 require 'rdstation/client'
 require 'rdstation/contacts'
 require 'rdstation/events'

data/lib/rdstation/api_response.rb

@@ -2,8 +2,9 @@ module RDStation
   module ApiResponse
     def self.build(response)
       response_body = JSON.parse(response.body)
-      return response_body unless response_body['errors']
-      RDStation::ErrorHandler.new(response).raise_errors
+      return response_body if response.code.between?(200, 299)
+
+      RDStation::ErrorHandler.new(response).raise_error
     end
   end
 end

data/lib/rdstation/authorization_header.rb

@@ -0,0 +1,21 @@
+module RDStation
+  class AuthorizationHeader
+    
+    def initialize(access_token:)
+      @access_token = access_token
+      validate_access_token access_token
+    end
+    
+    def to_h
+      { "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,90 +1,23 @@
-# encoding: utf-8
 module RDStation
-  #
-  # Mais informações em http://ajuda.rdstation.com.br/hc/pt-br/articles/204526429-Guia-de-integra%C3%A7%C3%B5es-com-o-RD-Station
-  #
   class Client
-    include HTTParty
-
-    def initialize(rdstation_token, auth_token, identifier="integração")
-      warn "DEPRECATION WARNING: all methods in this class has been deprecated because the version 1.x is no longer under active development and will be removed in version 2.0.0. See more details about the new version here: https://developers.rdstation.com/en/overview"
-      @identificador = identifier
-      @rdstation_token = rdstation_token
-      @auth_token = auth_token
-    end
-
-    #
-    # A hash do Lead pode conter os seguintes parâmetros:
-    # (obrigatório) :email
-    #               :identificador
-    #               :nome
-    #               :empresa
-    #               :cargo
-    #               :telefone
-    #               :celular
-    #               :website
-    #               :twitter
-    #               :c_utmz
-    #               :created_at
-    #               :tags
-    #
-    # Caso algum parâmetro não seja identificado como campo padrão ou como
-    # campo personalizado, este parâmetro desconhecido será gravado nos
-    # "Detalhes do Lead".
-    #
-    def create_lead(lead_hash)
-      warn "DEPRECATION WARNING: create_lead has been deprecated because the version 1.x is no longer under active development and will be removed in version 2.0.0. See more details about the new version here: https://developers.rdstation.com/en/overview"
-      lead_hash = rdstation_token_hash.merge(lead_hash)
-      lead_hash = lead_hash.merge(identifier_hash) unless lead_hash.has_key?(:identificador)
-      post_with_body("/conversions", {:body => lead_hash})
-    end
-    alias_method :update_lead_info, :create_lead
-
-    #
-    # param lead:
-    #   id ou email do Lead a ser alterado
-    #
-    # param lead_hash:
-    #   Hash contendo:
-    #     :lifecycle_stage
-    #       0 - Lead; 1 - Lead Qualificado; 2 - Cliente
-    #     :opportunity
-    #       true ou false
-    #
-    def change_lead(lead, lead_hash)
-      warn "DEPRECATION WARNING: change_lead has been deprecated because the version 1.x is no longer under active development and will be removed in version 2.0.0. See more details about the new version here: https://developers.rdstation.com/en/overview"
-      lead_hash = auth_token_hash.merge({:lead => lead_hash})
-      put_with_body("/leads/#{lead}", :body => lead_hash.to_json, :headers => {'Content-Type' => 'application/json'})
-    end
-
-    def change_lead_status(lead_hash)
-      warn "DEPRECATION WARNING: change_lead_status has been deprecated because the version 1.x is no longer under active development and will be removed in version 2.0.0. See more details about the new version here: https://developers.rdstation.com/en/overview"
-      post_with_body("/services/#{@auth_token}/generic", :body => lead_hash )
-    end
-
-  private
-    def base_url
-      "https://www.rdstation.com.br/api/1.2"
+    def initialize(access_token:)
+      @authorization_header = AuthorizationHeader.new(access_token: access_token)
     end
-
-    def rdstation_token_hash
-      { :token_rdstation => @rdstation_token }
-    end
-
-    def auth_token_hash
-      { :auth_token => @auth_token }
+    
+    def contacts
+      @contacts ||= RDStation::Contacts.new(authorization_header: @authorization_header)
     end
 
-    def identifier_hash
-      { :identificador => @identificador }
+    def events
+      @events ||= RDStation::Events.new(authorization_header: @authorization_header)
     end
 
-    def post_with_body(path, opts)
-      self.class.post("#{base_url}#{path}", opts)
+    def fields
+      @fields ||= RDStation::Fields.new(authorization_header: @authorization_header)
     end
 
-    def put_with_body(path, opts)
-      self.class.put("#{base_url}#{path}", opts)
+    def webhooks
+      @webhooks ||= RDStation::Webhooks.new(authorization_header: @authorization_header)
     end
   end
 end