qbo_api 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9705a6a9fde66e76546b9203e846d505dd5d3f15
-  data.tar.gz: 171efdaf99db8369c5a7abe900ee2be306600a10
+  metadata.gz: fa54c3e368cbe905ae5b328cdac7de62ba744f05
+  data.tar.gz: d52eaa3b8dfddc1ecafd1e8860235317f972682c
 SHA512:
-  metadata.gz: c4ce0818cb0ef23707b903d765d092b6e2a784d1e3cfe2ac570cbe4be31d25a9bf91dc5dfde76281b62279543f31b650c67dd25591f0a1c8c991cf5ea2910da6
-  data.tar.gz: 8a9007b00ec9464125a5851c97a5f1754cc74472ff2292a0fbc7a505140b89693958632e2757f618988aa25900a7608df6d29d35a2f42f5cc251e38d98217bdc
+  metadata.gz: 5df20a423bea757d0ecdecb67d3c096758ebd381d5e61a6175ef52c5959d5d7d8aa2e558fb7b8c60a38be6f74050b301bbe53f01221ef4572af924d6ab961a16
+  data.tar.gz: 601d278a518e73d0a29844e5d2f9e73a2eb1388b424a3f87b6398955d6c034292a3cdf108fe753ea949e30ae1d90870710f45f94546f8a1c6f265930a368c03d

data/.travis.yml

@@ -1,4 +1,9 @@
 language: ruby
 rvm:
   - 2.2.2
-before_install: gem install bundler -v 1.10.6
+  - 2.3.0
+
+sudo: false
+notifications:
+  email:
+    - christian@minimul.com

data/README.md

@@ -36,7 +36,26 @@ Or install it yourself as:
 ### Initialize
 ```ruby
   q = account.qbo_account # or wherever you are storing the OAuth creds
-  qbo_api = QboApi.new(token: q.token, token_secret: q.secret, realm_id: q.companyid)
+  qbo_api = QboApi.new(token: q.token,
+                       token_secret: q.secret,
+                       realm_id: q.companyid,
+                       consumer_key: '*****',
+                       consumer_secret: '********')
+```
+
+### Super fast way to use QboApi no matter your current tech stack as long as Ruby > 2.2.2 is installed
+```
+- cd ~/<local dir>
+- git clone git@github.com:minimul/qbo_api.git && cd qbo_api
+- bundle
+- bin/console
+- QboApi.production = true
+- qboapi = QboApi.new(token: "qyprd2uvCOdRq8xzoSSiiiiii",
+                      token_secret:"g8wcyQEtwxxxxxxm",
+                      realm_id: "12314xxxxxx7",
+                      consumer_key: "qyprdwzcxxxxxxbIWsIMIy9PYI",
+                      consumer_secret: "CyDN4wpxxxxxxxPMv7hDhmh4")
+- qboapi.get :customer, 1
 ```
 
 ### Configuration options
@@ -52,6 +71,10 @@ QboApi.log = true
 ```ruby
 QboApi.logger = Rails.logger
 ```
+- To run all create, modify, and delete requests with unique [RequestIds](https://developer.intuit.com/hub/blog/2015/04/06/15346).
+```ruby
+QboApi.request_id = true
+```
 
 ### Create
 ```ruby
@@ -114,6 +137,60 @@ QboApi.logger = Rails.logger
   p ids
 ```
 
+### Batch operations (limit 30 operations in 1 batch request)
+```ruby
+  payload = {
+      "BatchItemRequest":
+      [
+        {
+          "bId": "bid1",
+          "operation": "create",
+          "Vendor": {
+            "DisplayName": "Smith Family Store"
+          }
+        }, {
+          "bId": "bid2",
+          "operation": "delete",
+          "Invoice": {
+            "Id": "129",
+            "SyncToken": "0"
+          }
+        }
+      ]
+  }
+  response = api.batch(payload)
+  expect(response['BatchItemResponse'].size).to eq 2
+  expect(batch_response.detect{ |b| b["bId"] == "bid1" }["Vendor"]["DisplayName"]).to eq "Smith Family Store"
+```
+
+### Reports
+
+```ruby
+        params = { start_date: '2015-01-01', end_date: '2015-07-31', customer: 1, summarize_column_by: 'Customers' }
+        response = api.reports(name: 'ProfitAndLoss', params: params)
+        p response["Header"]["ReportName"]) #=> 'ProfitAndLoss'
+```
+
+### Reconnect
+
+See [docs](https://developer.intuit.com/docs/0100_quickbooks_online/0100_essentials/0085_develop_quickbooks_apps/0004_authentication_and_authorization/oauth_management_api#/Reconnect)
+```ruby
+        response = qbo_api.reconnect
+        #=> if response['ErrorCode'] == 0
+        #=>   p response['OAuthToken'] #=> rewq23423424afadsdfs==
+        #=>   p response['OAuthTokenSecret'] #=> ertwwetu12345312005343453yy=Fg
+```
+
+### Disconnect
+
+See [docs](https://developer.intuit.com/docs/0100_quickbooks_online/0100_essentials/0085_develop_quickbooks_apps/0004_authentication_and_authorization/oauth_management_api#/Disconnect)
+```ruby
+        response = qbo_api.disconnect
+        #=> if response['ErrorCode'] == 0
+        #=>   # Successful disconnect
+```
+
+
 ### Respond to an error
 ```ruby
   customer = { DisplayName: 'Weiskopf Consulting' } 
@@ -178,6 +255,9 @@ export QBO_API_CONSUMER_SECRET=<Your QuickBooks apps consumer secret>
   - You should see "Dukes Basketball Camp" displayed
 - Checkout [`example/app.rb`](https://github.com/minimul/qbo_api/blob/master/example/app.rb) to see what is going on under the hood.
 
+## Webhooks
+- <a href="http://minimul.com/getting-started-with-quickbooks-online-webhooks.html" target="_blank">Check out this tutorial and screencast on handling a webhook request</a>. Also checkout [`example/app.rb`](https://github.com/minimul/qbo_api/blob/master/example/app.rb) for the request handling code.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/minimul/qbo_api.
@@ -201,6 +281,15 @@ export QBO_API_COMPANY_ID=12345
 - All specs that require interaction with the API must be recorded against your personal QuickBooks sandbox. More coming on how to create or modifying existing specs against your sandbox.
 - <a href="http://minimul.com/the-modern-ruby-quickbooks-client-contributing.html" target="_blank">Check out this tutorial and screencast on contributing to qbo_api</a>.
 
+#### Protip: Once your .env file is completely filled out you can use the console to play around in your sandbox
+```
+bin/console
+>> require_relative 'spec/spec_helper'
+>> VCR.configure { |c| c.allow_http_connections_when_no_cassette = true }
+>> q = QboApi.new(creds.to_h)
+>> q.get :customer, 1
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/example/app.rb

@@ -1,6 +1,8 @@
 require "bundler/setup"
 require 'sinatra'
 require 'json'
+require 'openssl'
+require 'base64'
 require 'omniauth'
 require 'omniauth-quickbooks'
 require 'dotenv'
@@ -10,13 +12,22 @@ Dotenv.load "#{__dir__}/../.env"
 PORT  = 9393
 CONSUMER_KEY = ENV['QBO_API_CONSUMER_KEY']
 CONSUMER_SECRET = ENV['QBO_API_CONSUMER_SECRET']
+VERIFIER_TOKEN = ENV['QBO_API_VERIFIER_TOKEN']
 
 set :port, PORT
-use Rack::Session::Cookie
+use Rack::Session::Cookie, secret: '34233adasf'
 use OmniAuth::Builder do
   provider :quickbooks, CONSUMER_KEY, CONSUMER_SECRET
 end
 
+helpers do
+  def verify_webhook(data, hmac_header)
+    digest  = OpenSSL::Digest.new('sha256')
+    calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, VERIFIER_TOKEN, data)).strip
+    calculated_hmac == hmac_header
+  end
+end
+
 get '/' do
   @app_center = QboApi::APP_CENTER_BASE
   @auth_data = oauth_data
@@ -32,6 +43,14 @@ get '/customer/:id' do
   erb :customer
 end
 
+post '/webhooks' do
+  request.body.rewind
+  data = request.body.read
+  puts JSON.parse data
+  verified = verify_webhook(data, env['HTTP_INTUIT_SIGNATURE'])
+  puts "Verified: #{verified}"
+end
+
 def oauth_data
   {
     consumer_key: CONSUMER_KEY,

data/lib/qbo_api.rb

@@ -1,11 +1,13 @@
 require 'qbo_api/version'
 require 'json'
-#require 'rack'
+require 'uri'
+require 'securerandom'
 require 'logger'
 require 'faraday'
 require 'faraday_middleware'
 require 'faraday/detailed_logger'
 require_relative 'qbo_api/configuration'
+require_relative 'qbo_api/supporting'
 require_relative 'qbo_api/error'
 require_relative 'qbo_api/raise_http_exception'
 require_relative 'qbo_api/entity'
@@ -13,6 +15,7 @@ require_relative 'qbo_api/util'
 
 class QboApi
   extend Configuration
+  include Supporting
   include Entity
   include Util
   attr_reader :realm_id
@@ -53,11 +56,6 @@ class QboApi
     request(:get, entity: entity, path: path)
   end
 
-  def cdc(entities:, changed_since:)
-    path = "#{realm_id}/cdc?entities=#{entities}&changedSince=#{cdc_time(changed_since)}"
-    request(:get, path: path)
-  end
-
   def get(entity, id)
     path = "#{entity_path(entity)}/#{id}"
     request(:get, entity: entity, path: path)
@@ -74,19 +72,21 @@ class QboApi
 
   def delete(entity, id:)
     raise QboApi::NotImplementedError unless is_transaction_entity?(entity)
-    path = "#{entity_path(entity)}?operation=delete"
+    path = add_params_to_path(path: entity_path(entity), params: { operation: :delete })
     payload = set_update(entity, id)
     request(:post, entity: entity, path: path, payload: payload)
   end
 
   # TODO: Need specs for disconnect and reconnect
-  # https://developer.intuit.com/docs/0100_accounting/0060_authentication_and_authorization/oauth_management_api
+  # https://developer.intuit.com/docs/0100_quickbooks_online/0100_essentials/0085_develop_quickbooks_apps/0004_authentication_and_authorization/oauth_management_api#/Reconnect
   def disconnect
-    response = connection(url: APP_CONNECTION_URL).get('/disconnect')
+    path = "#{APP_CONNECTION_URL}/disconnect"
+    request(:get, path: path)
   end
 
   def reconnect
-    response = connection(url: APP_CONNECTION_URL).get('/reconnect')
+    path = "#{APP_CONNECTION_URL}/reconnect"
+    request(:get, path: path)
   end
 
   def all(entity, max: 1000, select: nil, &block)
@@ -107,7 +107,7 @@ class QboApi
       when :get, :delete
         req.url URI.encode(path)
       when :post, :put
-        req.url path
+        req.url add_request_id_to(path)
         req.body = JSON.generate(payload)
       end
     end

data/lib/qbo_api/configuration.rb

@@ -24,5 +24,13 @@ class QboApi
     def production=(value)
       @production = value
     end
+
+    def request_id
+      @request_id ||= false
+    end
+
+    def request_id=(value)
+      @request_id = value
+    end
   end
 end

data/lib/qbo_api/entity.rb

@@ -73,6 +73,7 @@ class QboApi
     def supporting_entities
       %w{
         Attachable
+        Batch
         CompanyInfo
         Entitlements
         ExchangeRate

data/lib/qbo_api/error.rb

@@ -4,7 +4,8 @@
 #401 Unauthorized	Authentication or authorization has failed.
 #403 Forbidden	The resource is forbidden.
 #404 Not Found	The resource is not found.
-#500 Internal Server Error	An error occured on the server while processing the request.  Resubmit request once; if it persists, contact developer support.
+#429 Too Many Requests  API Throttling/ Rate limiting
+#500 Internal Server Error	An error occurred on the server while processing the request.  Resubmit request once; if it persists, contact developer support.
 #503 Service Unavailable	The service is temporarily unavailable.
 # Custom error class for rescuing from all QuickBooks Online errors
 class QboApi
@@ -33,6 +34,9 @@ class QboApi
   # Raised when QuickBooks Online returns the HTTP status code 404
   class NotFound < Error; end
 
+  # Raised when QuickBooks Online returns the HTTP status code 429
+  class TooManyRequests < Error; end
+
   # Raised when QuickBooks Online returns the HTTP status code 500
   class InternalServerError < Error; end
 

data/lib/qbo_api/raise_http_exception.rb

@@ -9,8 +9,6 @@ module FaradayMiddleware
       @app.call(env).on_complete do |response|
         case response.status
         when 200
-          # 200 responses can have errors
-          raise QboApi::BadRequest.new(error_message(response)) if response.body =~ /Fault.*Error.*Message/
         when 400
           raise QboApi::BadRequest.new(error_message(response))
         when 401
@@ -19,6 +17,8 @@ module FaradayMiddleware
           raise QboApi::Forbidden.new(error_message(response))
         when 404
           raise QboApi::NotFound.new(error_message(response))
+        when 429
+          raise QboApi::TooManyRequests.new(error_message(response))
         when 500
           raise QboApi::InternalServerError.new(error_message(response))
         when 503

data/lib/qbo_api/supporting.rb

@@ -0,0 +1,21 @@
+class QboApi
+  module Supporting
+
+    def cdc(entities:, changed_since:)
+      path = "#{realm_id}/cdc?entities=#{entities}&changedSince=#{cdc_time(changed_since)}"
+      request(:get, path: path)
+    end
+
+    def batch(payload)
+      path = "#{realm_id}/batch"
+      request(:post, path: path, payload: payload)
+    end
+
+    def reports(name:, params: nil)
+      path = "#{realm_id}/reports/#{name}"
+      path = add_params_to_path(path: path, params: params) if params
+      request(:get, path: path)
+    end
+
+  end
+end

data/lib/qbo_api/util.rb

@@ -7,6 +7,28 @@ class QboApi
         time.to_s.sub(' ', 'T').sub(' ', '').insert(-3, ':')
       end
     end
+
+    def uuid
+      SecureRandom.uuid
+    end
+
+    def add_request_id_to(path)
+      if QboApi.request_id
+        add_params_to_path(path: path, params: { "requestid" => uuid })
+      else
+        path
+      end
+    end
+
+    def add_params_to_path(path:, params:)
+      uri = URI.parse(path)
+      params.each do |p|
+        new_query_ar = URI.decode_www_form(uri.query || '') << p.to_a
+        uri.query = URI.encode_www_form(new_query_ar)
+      end
+      uri.to_s
+    end
+
   end
 end
 

data/lib/qbo_api/version.rb

@@ -1,3 +1,3 @@
 class QboApi
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/qbo_api.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'omniauth-quickbooks'
   spec.add_development_dependency 'dotenv'
   spec.add_development_dependency 'vcr'
+  spec.add_development_dependency 'awesome_print'
   spec.add_runtime_dependency 'faraday'
   spec.add_runtime_dependency 'faraday_middleware'
   spec.add_runtime_dependency 'faraday-detailed_logger'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qbo_api
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Christian Pelczarski
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-28 00:00:00.000000000 Z
+date: 2016-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -136,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -229,6 +243,7 @@ files:
 - lib/qbo_api/entity.rb
 - lib/qbo_api/error.rb
 - lib/qbo_api/raise_http_exception.rb
+- lib/qbo_api/supporting.rb
 - lib/qbo_api/util.rb
 - lib/qbo_api/version.rb
 - qbo_api.gemspec