qbo_api 2.0.2 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 162fa8b773e3b73b82ea03e73d06ded342f6ac3bc7daafc9c02cc6a965a34aa7
-  data.tar.gz: a074c58fe2826531c2fe7a04cee0fecaf4021aac7e2c9a64fc30062fd3602fd5
+  metadata.gz: d091daea142ea8b5f0637e93068ebec256c6ed5027b03725b576e003fa1997b3
+  data.tar.gz: d44cdfc123b586c2ee4a228f06ffa0d6c602e8897c18cfb656fd68aa7a7401c3
 SHA512:
-  metadata.gz: 29a5b45354f2dbd9978fee3498dbfa96b660c6c747b93432b00836079f64e35d1448463ba13f055fc866e85804981f0a8110b6a429f23fc118da8a9f732d003b
-  data.tar.gz: f733937e458917500539ad443c8bfe61d29584b00caa2d8b7824d525170d2058806a7ad5e6a6a485ac05a6adf45be18feed8afff53372a7b7f643dd1fa1d40c2
+  metadata.gz: 61177b17927c994c049cc7975f0673b9893f04c39d7f0b61ec5af4d2a15d13ad0cfbf0fac5302b33ffedeeda43f5af474d22112a8ca1b22d7cf5fa31097fbae8
+  data.tar.gz: de16113918a2d51488654197f585d60f480e40aa107d51e5de471ae418cabf7c01c0691a57d8acbe4bf732610d1f1b6c049317cb2c7a9d08ce09fa21ab876a81

data/.github/dependabot.yml

@@ -0,0 +1,10 @@
+# Set update schedule for GitHub Actions
+
+version: 2
+updates:
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every weekday
+      interval: "daily"

data/.github/workflows/ci.yaml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+
+jobs:
+  rspec:
+    runs-on: ubuntu-latest
+    env:
+      RUBYOPT: "-W:deprecated" # show warnings, deprecations only
+      FARADAY_VERSION: ${{ matrix.faraday }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ '2.7', '3.0', '3.1', '3.2' ]
+        faraday: [ '~> 1.0', '~> 2.0' ]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run RSpec
+        run: |
+          cp .env.test .env
+          bundle exec rspec spec/

data/.gitignore

@@ -19,4 +19,4 @@ todo.txt
 spec/temp/spec_status.txt
 *.swp
 scrap.txt
-.tool-versions
+.tool-versions

data/README.md

@@ -81,7 +81,7 @@ QboApi.request_id = true
   resp = qbo_api.create(:bill, payload: bill_hash, params: { requestid: qbo_api.uuid })
   # Works with .get, .create, .update, .query methods
 ```
-- To run all requests with a [Minor version](https://developer.intuit.com/docs/0100_quickbooks_online/0200_dev_guides/accounting/minor_versions).
+- By default, this client runs against the current "base" or major version of the QBO API. This client does not run against the latest QBO API [minor version](https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/minor-versions) by default. To run all requests with a specific minor version, you must specify it:
 ```ruby
 QboApi.minor_version = 8
 ```
@@ -132,6 +132,12 @@ QboApi.minor_version = 8
   p response['status'] # => "Deleted"
 ```
 
+NOTE: If you are deleting a journal entry you have to use the following syntax with the underscore, even though this is inconsistent with how you create journal entries.
+```ruby
+  response = qbo_api.delete(:journal_entry, id: 145)
+  p response['status'] # => "Deleted"
+```
+
 ### Deactivate (only works for name list entities)
 ```ruby
   response = qbo_api.deactivate(:employee, id: 55)
@@ -329,29 +335,78 @@ See [docs](https://developer.intuit.com/docs/0100_quickbooks_online/0100_essenti
   p qbo_api.is_transaction_entity?(:customer) # => false
   p qbo_api.is_name_list_entity?(:vendors) # => true
 ```
-## <a name='OAuth2-example'>Spin up an example</a>
+
+### Download Quickbooks PDF
+A quickbooks supplied PDF can be downloaded for api endpoints which offer a PDF.
+```ruby
+qbo_api.get_pdf(:invoice, 121) # produces a pdf stream.
+```
+The PDF stream can then be saved using your preferred method.
+```ruby
+# example using Ruby on Rails with ActiveStorage
+class Invoice
+  has_one_attached :pdf_file
+end
+invoice_number = 121
+pdf_data = qbo_api.get_pdf(:invoice, invoice_numer) # returns raw pdf stream
+pdf_io = StringIO.new(pdf_data) # convert to a StringIO object
+filename = "invoice_no_#{invoice_number}"
+
+invoice.pdf_file.attach(
+    io: pdf_io,
+    filename: filename,
+    content_type: 'application/pdf'
+)
+```
+
+```ruby
+# plain ruby example
+invoice_number = 121
+pdf_data = qbo_api.get_pdf(:invoice, invoice_numer) # returns raw pdf stream
+filename = "invoice_no_#{invoice_number}.pdf"
+
+File.write(filename, pdf_data)
+```
+## Spin up an example
 - <a href="http://minimul.com/access-the-quickbooks-online-api-with-oauth2.html" target="_blank">Check out this article on spinning up the example</a>.
-- `git clone git://github.com/minimul/qbo_api && cd qbo_api`
-- `bundle`
+
+- Create a Intuit developer account at [https://developer.intuit.com](https://developer.intuit.com)
+- Create an app in the intuit developer backend
+  - Go to [myapps](https://developer.intuit.com/app/developer/myapps)
+  - Create an app with both the `Accounting` & `Payments` selected.
+
+- Setup the app and gather credentials
+  - Go to the [Development Dashboard](https://developer.intuit.com/app/developer/dashboard)
+  - Click on your App name
+  - Click "Keys & credentials" under Development Settings in left menu
+  - Copy the 'Client ID' and the 'Client Secret'
+  - Add a Redirect URI: `http://localhost:9393/oauth2-redirect` (or whatever PORT= is in your .env)
+  - Create a new Sandbox Company by clicking on "View Sandbox companies"
+    Don't use it for anything else besides testing this app.
+  - Copy the 'Company ID' for use later
+    1. Within 'Sandbox Company_US_1' click on the COG -> Additional info
+    2. Copy the 'Company ID'
+  
+- Setup qbo_api
+  - `git clone git://github.com/minimul/qbo_api && cd qbo_api`
+  - `bundle`
+
 - Create a `.env` file
   - `cp .env.example_app.oauth2 .env`
-  - If needed create an account at [https://developer.intuit.com](https://developer.intuit.com)
-  - Click `Get started coding`
-  - Create an app with both the `Accounting` & `Payments` selected.
-  - Go to the [`Development` tab](https://developer.intuit.com/v2/ui#/app/dashboard)
-  and copy the 'Client ID' and the 'Client 'Secret' to your .env
-  as QBO_API_CLIENT_ID and QBO_API_CLIENT_SECRET respectively
-- Add a Redirect URI: `http://localhost:9393/oauth2-redirect` (or whatever PORT= is in your .env)
-- Create a new Company ([from the manage sandboxes page](https://developer.intuit.com/v2/ui#/sandbox))
-  Don't use it for anything else besides testing this app.
--. Copy the 'Company ID' to your .env as QBO_API_COMPANY_ID
-- Start up the example app
+  - Edit your .env and enter the following
+    ```
+    export QBO_API_CLIENT_ID=[YOUR CLIENT ID]
+    export QBO_API_CLIENT_SECRET=[YOUR CLIENT SECRET]
+    export QBO_API_COMPANY_ID=[YOUR COMPANY ID]
+    ```
+
+- Start up the example app and test
   - `ruby example/oauth2.rb`
-- Go to `http://localhost:9393/oauth2`
-- Use the `Connect to QuickBooks` button to connect to your QuickBooks sandbox, which you receive when signing up at [https://developer.intuit.com](https://developer.intuit.com).
-- After successfully connecting to your sandbox go to :
-  - `http://localhost:9393/oauth2/customer/5`
+  - Go to `http://localhost:9393/oauth2`
+  - Use the `Connect to QuickBooks` button to connect to your QuickBooks sandbox, which you receive when signing up at [https://developer.intuit.com](https://developer.intuit.com).
+  - After successfully connecting to your sandbox go to `http://localhost:9393/oauth2/customer/5`
   - You should see "Dukes Basketball Camp" displayed
+
 - Checkout [`example/oauth2.rb`](https://github.com/minimul/qbo_api/blob/master/example/oauth2.rb)
   to see what is going on under the hood.
 
@@ -372,8 +427,8 @@ for how to install ngrok and what it is.
   Add the token to your .env as QBO_API_VERIFIER_TOKEN
 
 - In another tab, create a customer via the API:
-  `bundle exec ruby -rqbo_api -rdotenv -e 'Dotenv.load; p QboApi.new(access_token: ENV.fetch("QBO_API_OAUTH2_ACCESS_TOKEN"), realm_id: ENV.fetch("QBO_API_COMPANY_ID")).create(:customer, payload: { DisplayName: "TestCustomer" })'`
-  (You'll also need to have added the QBO_API_COMPANY_ID and QBO_API_OAUTH2_ACCESS_TOKEN to your .env)
+  `bundle exec ruby -rqbo_api -rdotenv -e 'Dotenv.load; p QboApi.new(access_token: ENV.fetch("QBO_API_ACCESS_TOKEN"), realm_id: ENV.fetch("QBO_API_COMPANY_ID")).create(:customer, payload: { DisplayName: "TestCustomer" })'`
+  (You'll also need to have added the QBO_API_COMPANY_ID and QBO_API_ACCESS_TOKEN to your .env)
 
   There could be a delay of up to a minute before the webhook fires.
 
@@ -391,8 +446,8 @@ for how to install ngrok and what it is.
 connection = build_connection('https://oauth.platform.intuit.com', headers: { 'Accept' => 'application/json' }) do |conn|
   conn.basic_auth(client_id, client_secret)
   conn.request :url_encoded # application/x-www-form-urlencoded
-  conn.use FaradayMiddleware::ParseJson, parser_options: { symbolize_names: true }
-  conn.use Faraday::Response::RaiseError
+  conn.response :json
+  conn.use QboApi::RaiseHttpException
 end
 
 raw_response = connection.post do |req|

data/example/base.rb

@@ -3,6 +3,7 @@ BASE_GEMS = proc do
   # This app
   gem 'sinatra'
   gem 'sinatra-contrib'
+  gem 'puma'
 
   # Creds from ../.env
   gem 'dotenv'

data/lib/qbo_api/api_methods.rb

@@ -34,6 +34,11 @@ class QboApi
       end
     end
 
+    def get_pdf(entity, id)
+      path = "#{entity_path(entity)}/#{id}/pdf"
+      request(:get, entity: entity, path: path, headers: { 'Accept' => 'application/pdf' })
+    end
+
     def create(entity, payload:, params: nil)
       request(:post, entity: entity, path: entity_path(entity), payload: payload, params: params)
     end
@@ -58,6 +63,14 @@ class QboApi
       request(:post, entity: entity, path: entity_path(entity), payload: payload)
     end
 
+    def void(entity, id:)
+      err_msg = "Void is only for voidable transaction entities. Use .delete or .deactivate instead"
+      raise QboApi::NotImplementedError.new, err_msg unless is_voidable_transaction_entity?(entity)
+      path = add_params_to_path(path: entity_path(entity), params: { operation: :void })
+      payload = set_update(entity, id)
+      request(:post, entity: entity, path: path, payload: payload)
+    end
+
     private
 
     def get_query_str(entity, query_filter_args)

data/lib/qbo_api/connection.rb

@@ -1,6 +1,8 @@
 require 'faraday'
-require 'faraday_middleware'
+require 'faraday/response/json'
+require 'qbo_api/raise_http_exception'
 require 'faraday/detailed_logger'
+require 'faraday/multipart'
 
 class QboApi
   module Connection
@@ -9,9 +11,10 @@ class QboApi
       headers['Accept'] ||= 'application/json'
       headers['Content-Type'] ||= 'application/json;charset=UTF-8'
       build_connection(url, headers: headers) do |conn|
+        conn.response :json
         add_authorization_middleware(conn)
-        add_exception_middleware(conn)
         conn.request :url_encoded
+        add_exception_middleware(conn)
         add_connection_adapter(conn)
       end
     end
@@ -22,6 +25,7 @@ class QboApi
         'Accept' => 'application/json'
       }
       build_connection(url, headers: headers) do |conn|
+        conn.response :json
         add_authorization_middleware(conn)
         add_exception_middleware(conn)
         conn.request :multipart
@@ -39,7 +43,7 @@ class QboApi
 
     def request(method, path:, entity: nil, payload: nil, params: nil, headers: nil)
       raw_response = raw_request(method, conn: connection, path: path, params: params, payload: payload, headers: headers)
-      response(raw_response, entity: entity)
+      response(raw_response, entity: entity, headers: headers)
     end
 
     def raw_request(method, conn:, path:, payload: nil, params: nil, headers: nil)
@@ -59,22 +63,20 @@ class QboApi
       end
     end
 
-    def response(resp, entity: nil)
-      data = parse_response_body(resp)
+    def response(resp, entity: nil, headers: false)
+      data = resp.body
+
+      if headers
+        content_type = headers['Accept'] || headers['Content-Type']
+        return data if content_type&.include?('application/pdf')
+      end
+
       entity ? entity_response(data, entity) : data
     rescue => e
       QboApi.logger.debug { "#{LOG_TAG} response parsing error: entity=#{entity.inspect} body=#{resp.body.inspect} exception=#{e.inspect}" }
       data
     end
 
-    def parse_response_body(resp)
-      body = resp.body
-      case resp.headers['Content-Type']
-      when /json/ then JSON.parse(body)
-      else body
-      end
-    end
-
     private
 
     def entity_response(data, entity)
@@ -101,11 +103,14 @@ class QboApi
     end
 
     def add_exception_middleware(conn)
-      conn.use FaradayMiddleware::RaiseHttpException
+      conn.use QboApi::RaiseHttpException
     end
 
+    # Faraday 2 deprecated the FaradayMiddleware gem. Middleware is
+    # now part of Faraday itself, and :authorization can be used to pass
+    # the Bearer token.
     def add_authorization_middleware(conn)
-      conn.request :oauth2, access_token, token_type: 'bearer'
+      conn.request :authorization, 'Bearer', access_token
     end
 
     def entity_name(entity)

data/lib/qbo_api/entity.rb

@@ -20,6 +20,19 @@ class QboApi
       sym.to_s.split('_').collect(&:capitalize).join
     end
 
+    def is_voidable_transaction_entity?(entity)
+      voidable_transaction_entities.include?(singular(entity))
+    end
+
+    def voidable_transaction_entities
+      %w{
+        BillPayment
+        Invoice
+        Payment
+        SalesReceipt
+      }
+    end
+
     def is_transaction_entity?(entity)
       transaction_entities.include?(singular(entity))
     end

data/lib/qbo_api/error.rb

@@ -13,11 +13,25 @@ class QboApi
   class Error < StandardError
     attr_reader :fault
 
-    def initialize(errors = nil)
-      if errors
-        @fault = errors
-        super(errors[:error_body])
-      end
+    def initialize(errors = {})
+      @fault = errors
+      super(errors[:error_body])
+    end
+
+    def fault_type
+      fault.dig(:error_body, 0, :fault_type)
+    end
+
+    def error_code
+      fault.dig(:error_body, 0, :error_code)
+    end
+
+    def error_message
+      fault.dig(:error_body, 0, :error_message)
+    end
+
+    def error_detail
+      fault.dig(:error_body, 0, :error_detail)
     end
   end
 

data/lib/qbo_api/raise_http_exception.rb

@@ -1,32 +1,44 @@
 require 'faraday'
+require 'faraday/response'
 require 'nokogiri'
 # @private
-module FaradayMiddleware
+class QboApi
   # @private
-  class RaiseHttpException < Faraday::Middleware
-    def call(env)
-      @app.call(env).on_complete do |response|
-        case response.status
-        when 200
-        when 400
-          raise QboApi::BadRequest.new(error_message(response))
-        when 401
-          raise QboApi::Unauthorized.new(error_message(response))
-        when 403
-          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 502
-          raise QboApi::BadGateway.new({ error_body: response.reason_phrase })
-        when 503
-          raise QboApi::ServiceUnavailable.new(error_message(response))
-        when 504
-          raise QboApi::GatewayTimeout.new(error_message(response))
-        end
+  class RaiseHttpException < Faraday::Response::RaiseError
+    def on_complete(env)
+      case env[:status]
+      when 400
+        raise QboApi::BadRequest.new(error_message(env))
+      when 401
+        raise QboApi::Unauthorized.new(error_message(env))
+      when 403
+        raise QboApi::Forbidden.new(error_message(env))
+      when 404
+        raise QboApi::NotFound.new(error_message(env))
+      when 407
+        # mimic the behavior that we get with proxy requests with HTTPS
+        msg = %(407 "Proxy Authentication Required")
+        raise Faraday::ProxyAuthError.new(msg, response_values(env))
+      when 409
+        raise Faraday::ConflictError, response_values(env)
+      when 422
+        raise Faraday::UnprocessableEntityError, response_values(env)
+      when 429
+        raise QboApi::TooManyRequests.new(error_message(env))
+      when 500
+        raise QboApi::InternalServerError.new(error_message(env))
+      when 502
+        raise QboApi::BadGateway.new({ error_body: env.reason_phrase })
+      when 503
+        raise QboApi::ServiceUnavailable.new(error_message(env))
+      when 504
+        raise QboApi::GatewayTimeout.new(error_message(env))
+      when ClientErrorStatuses
+        raise Faraday::ClientError, response_values(env)
+      when ServerErrorStatuses
+        raise Faraday::ServerError, response_values(env)
+      when nil
+        raise Faraday::NilStatusError, response_values(env)
       end
     end
 
@@ -36,13 +48,13 @@ module FaradayMiddleware
 
     private
 
-    def error_message(response)
+    def error_message(env)
       {
-        method: response.method,
-        url: response.url,
-        status: response.status,
-        error_body: error_body(response.body),
-        intuit_tid: response[:response_headers]['intuit_tid']
+        method: env.method,
+        url: env.url,
+        status: env.status,
+        error_body: error_body(env.body),
+        intuit_tid: env[:response_headers]['intuit_tid']
       }
     end
 

data/lib/qbo_api/version.rb

@@ -1,3 +1,3 @@
 class QboApi
-  VERSION = "2.0.2"
+  VERSION = "3.0.3"
 end

data/qbo_api.gemspec

@@ -25,8 +25,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'dotenv'
   spec.add_development_dependency 'vcr'
   spec.add_development_dependency 'amazing_print'
-  spec.add_runtime_dependency 'faraday'
-  spec.add_runtime_dependency 'faraday_middleware'
+  spec.add_runtime_dependency 'faraday', '>= 1.10.0'
   spec.add_runtime_dependency 'faraday-detailed_logger'
+  spec.add_runtime_dependency 'faraday-multipart'
   spec.add_runtime_dependency 'nokogiri'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qbo_api
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 3.0.3
 platform: ruby
 authors:
 - Christian Pelczarski
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-13 00:00:00.000000000 Z
+date: 2024-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,16 +114,16 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.10.0
 - !ruby/object:Gem::Dependency
-  name: faraday_middleware
+  name: faraday-detailed_logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,7 +137,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: faraday-detailed_logger
+  name: faraday-multipart
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -164,7 +164,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
+description: 
 email:
 - christian@minimul.com
 executables: []
@@ -173,6 +173,8 @@ extra_rdoc_files: []
 files:
 - ".env.example_app.oauth2"
 - ".env.test"
+- ".github/dependabot.yml"
+- ".github/workflows/ci.yaml"
 - ".gitignore"
 - ".travis.yml"
 - Gemfile
@@ -204,7 +206,7 @@ homepage: https://github.com/minimul/qbo_api
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -219,8 +221,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
-signing_key:
+rubygems_version: 3.3.26
+signing_key: 
 specification_version: 4
 summary: Ruby JSON-only client for QuickBooks Online API v3. Built on top of the Faraday
   gem.