added get_pdf method (#135)

.gitignore

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

README.md

@@ -335,6 +335,38 @@ 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
 ```
+
+### 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>.
 

lib/qbo_api/api_methods.rb

@@ -34,6 +34,11 @@ def get_by_query_filter(entity, query_filter_args, params: nil)
       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

lib/qbo_api/connection.rb

@@ -43,7 +43,7 @@ def build_connection(url, headers: nil)
 
     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)
@@ -63,8 +63,14 @@ def raw_request(method, conn:, path:, payload: nil, params: nil, headers: nil)
       end
     end
 
-    def response(resp, entity: nil)
+    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}" }

spec/api_methods_spec.rb

@@ -243,4 +243,17 @@
       end
     end
   end
+
+  describe 'get pdf' do
+    let(:entity) { :invoice }
+    let(:id) { '130' }
+
+    it 'requests the pdf of an invoice' do
+      use_cassette('get_pdf/invoice') do
+        result = api.get_pdf(entity, id)
+        pdf_starts_correctly = result&.match(/^%PDF-\d+(\.\d+)?/)
+        expect(pdf_starts_correctly).to be_truthy
+      end
+    end
+  end
 end