gini-api 0.9.9 → 0.9.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f482221a91704b834f741e93bc66ed8d387f673b
-  data.tar.gz: 7cabfa0aa95303038767caf0058ac02e6684d9cc
+  metadata.gz: d81c78fc0e2e77fb6989c207d25f942b4ad950c9
+  data.tar.gz: 6d10b26a592452d43ae292620eae7c0d5e41584f
 SHA512:
-  metadata.gz: 0819422ce704bd75d4ef24b46ee3566a980453e79819f541312cd6c08a49477f5178c2e7da36eda92c9c541b6dd4b2370ca2e57013c3974ae45477bf7d385c4e
-  data.tar.gz: b068d3ef18cf8daa7c9514c85c0fd69004e83f65c0f84f6b8bd4189a0589cfcf17b43ce7ab53366ffec32c201eee5b41d979343a9d767e88b4790a8f13144321
+  metadata.gz: e792d768ffb748685f4fed691745bc66e3f060dd330d4bf403ffcaea5d3383b265cda4ac3de9e6de84642f026a07a0b974cbefd83c5729069772b9bf395eeb8f
+  data.tar.gz: 14a55d19162f5312de7abe9bac09b4ef6ddea5d51b97278d20ef8b853644c6bd020ba476b8033e179bb9cec57e7b8003755c50e23092f28bd49cfa3d976a76f8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gini-api (0.9.9)
+    gini-api (0.9.10)
       logger
       oauth2
 

data/README.md

@@ -53,6 +53,11 @@ api.login(username: 'me@example.com', password: 'secret')
 ```ruby
 doc = api.upload('/tmp/my_doc.pdf')
 # => Gini::Api::Document
+fh = File.open('/tmp/scan.pdf', 'r')
+doc = api.upload(fh)
+# => Gini::Api::Document
+doc = api.upload('tmp/my_receipt.pdf', doctype_hint='Receipt')
+# => Gini::Api::Document
 doc.id
 # => "123456789-abcd-ef12-000000000000"
 doc.progress
@@ -148,12 +153,23 @@ doc.extractions.undefinedLabel
 # => nil
 ```
 
+#### Incubator
+
+The incubator Gini API is unstable and subject of change. It allows early access to immature features which are still in research or under development. Please refer to the official API documentation for further details.
+
+```ruby
+doc.extractions(incubator=true).amountLiters
+# => {:amountLiters=>{:entity=>"volume", :value=>"25.34:l", :box=>{:top=>1774.0, :left=>674.0, :width=>376.0, :height=>48.0, :page=>1}}
+doc.extractions(incubator=true)[:amountLiters]
+# => "25.34:l"
+```
+
 ### Submitting feedback
 
 ```ruby
 doc.extractions.bic = 'XXXXXXXX'
 # => 'XXXXXXXX'
-doc.extractions.bic = { value: 'XXXXXXXX', :box=>{:top=>2176.0, :left=>2000.0, :width=>173.0, :height=>50.0, :page=>1 }
+doc.extractions.bic = { value: 'XXXXXXXX', :box=>{ :top=>2176.0, :left=>2000.0, :width=>173.0, :height=>50.0, :page=>1 } }
 # => { value: 'XXXXXXXX', box: { top: 2176.0, left: 2000.0, width: 173.0, height: 50.0, page: 1 }
 doc.extractions.unknownLabel = 'XXXXXXXX'
 # => raises Gini::Api::DocumentError
@@ -186,6 +202,19 @@ end
 
 Please keep in mind that the amount of availabe instance variables differs depending on the error situation. For details please refer to the ```Gini::Api::Error``` class.
 
+## Submitting error reports
+
+If the processing result for a document was not satisfactory (e.g. extractions where empty or incorrect), you can create an error report for a document. This allows Gini to analyze and correct the problem that was found. The owner of this document must agree that Gini can use this document for debugging and error analysis. The returned errorId can be used to refer to the reported error towards the Gini support.
+
+```ruby
+doc = api.get('123456789-abcd-ef12-000000000000')
+# => Gini::Api::Document
+doc.report_error()
+# => deadbeef-dead-dead-beef-deadbeeeeef
+doc.report_error(summary='Just a short summary of the problem', description='A detailed description...')
+# => deadbeef-dead-dead-beef-deadbeeeeef
+```
+
 ## Developers
 
 ### Getting started

data/lib/gini-api/client.rb

@@ -25,6 +25,7 @@ module Gini
       # @option options [String]  :api_uri API URI (https://api.gini.net)
       # @option options [String]  :api_version API version to use (v1)
       # @option options [Logger]  :log logger object to use (initialized with STDOUT otherwise)
+      # @option options [String]  :user_agent HTTP User-Agent (gini-api-ruby/VERSION (Faraday vFaraday::VERSION))
       #
       # @example
       #   api = Gini::Api::Client.new(
@@ -42,6 +43,7 @@ module Gini
           upload_timeout: 90,
           processing_timeout: 180,
           log: Logger.new(STDOUT),
+          user_agent: "gini-api-ruby/#{VERSION} (Faraday v#{Faraday::VERSION})"
         }.merge(options)
 
         # Ensure mandatory keys are set
@@ -77,6 +79,9 @@ module Gini
         OAuth2::Response.register_parser(:gini_xml, [version_header(:xml)[:accept]]) do |body|
           MultiXml.parse(body) rescue body
         end
+        OAuth2::Response.register_parser(:gini_incubator, [version_header(:json, :incubator)[:accept]]) do |body|
+          MultiJson.load(body, symbolize_keys: true) rescue body
+        end
       end
 
       # Acquire OAuth2 token and popolate @oauth (instance of Gini::Api::OAuth.new)
@@ -106,11 +111,12 @@ module Gini
       # Version accept header based on @api_version
       #
       # @param [Symbol, String] type Expected response type (:xml, :json)
+      # @param [Symbol, String] version API version (:v1, :incubator)
       #
       # @return [Hash] Return accept header or empty hash
       #
-      def version_header(type = @api_type)
-        { accept: "application/vnd.gini.#{@api_version}+#{type}" }
+      def version_header(type = @api_type, version = @api_version)
+        { accept: "application/vnd.gini.#{version}+#{type}" }
       end
 
       # Request wrapper that sets URI and accept header
@@ -142,21 +148,24 @@ module Gini
 
       # Upload a document
       #
-      # @param [String] file path of the document to upload
+      # @param [String] file path or open filehandle of the document to upload
+      # @param [String] doctype_hint Document type hint to optimize results or get incubator results
       # @param [Float] interval Interval to poll progress
       #
       # @return [Gini::Api::Document] Return Gini::Api::Document object for uploaded document
       #
       # @example Upload and wait for completion
       #   doc = api.upload('/tmp/myfile.pdf')
+      # @example Upload with doctype hint
+      #   doc = api.upload('/tmp/myfile.pdf', doctype_hint='Receipt')
       # @example Upload and monitor progress
       #   doc = api.upload('/tmp/myfile.pdf') { |d| puts "Progress: #{d.progress}" }
       #
-      def upload(file, interval = 0.5, &block)
+      def upload(file, doctype_hint = nil, interval = 0.5, &block)
         duration = Hash.new(0)
 
         # Document upload
-        duration[:upload], response = upload_document(file)
+        duration[:upload], response = upload_document(file, doctype_hint)
 
         # Start polling (0.5s) when document has been uploaded successfully
         if response.status == 201
@@ -305,16 +314,18 @@ module Gini
 
       # Helper to upload document
       #
-      # @param [String] file location of document to be uploaded
+      # @param [String] file location of document or open filehandle to be uploaded
+      # @param [String] doctype_hint Document type hint to optimize results or get incubator results
       #
       # @return [Faraday::Response] Response object from upload
       #
-      def upload_document(file)
+      def upload_document(file, doctype_hint)
         response = nil
         duration = Benchmark.realtime do
           response = upload_connection.post do |req|
             req.options[:timeout] = @upload_timeout
-            req.url 'documents/'
+            req.url 'documents'
+            req.params[:doctype] = doctype_hint if doctype_hint
             req.headers['Content-Type']  = 'multipart/form-data'
             req.headers['Authorization'] = "Bearer #{@token.token}"
             req.headers.merge!(version_header)

data/lib/gini-api/document.rb

@@ -101,10 +101,12 @@ module Gini
 
       # Initialize extractions from @_links and return Gini::Api::Extractions object
       #
+      # @param [Boolean] incubator Return experimental extractions
+      #
       # @return [Gini::Api::Document::Extractions] Return Gini::Api::Document::Extractions object for uploaded document
       #
-      def extractions
-        @extractions ||= Gini::Api::Document::Extractions.new(@api, @_links[:extractions])
+      def extractions(incubator = false)
+        @extractions ||= Gini::Api::Document::Extractions.new(@api, @_links[:extractions], incubator)
       end
 
       # Initialize layout from @_links[:layout] and return Gini::Api::Layout object
@@ -145,6 +147,28 @@ module Gini
           )
         end
       end
+
+      # Submit error report on document
+      #
+      # @param [String] summary Short summary on the error found
+      # @param [String] description More detailed description of the error found
+      #
+      # @return [String] Error ID retured from API
+      #
+      def report_error(summary = nil, description = nil)
+        response = @api.request(
+          :post,
+          "#{@_links[:document]}/errorreport",
+          params: { summary: summary, description: description }
+        )
+        unless response.status == 200
+          raise Gini::Api::DocumentError.new(
+            "Failed to submit error report for document #{@id} (code=#{response.status})",
+            response
+          )
+        end
+        response.parsed[:errorId]
+      end
     end
   end
 end

data/lib/gini-api/document/extractions.rb

@@ -11,9 +11,17 @@ module Gini
       #
       # @param [Gini::Api::Client] api Gini::Api::Client object
       # @param [String] location Document URL
-      def initialize(api, location)
-        @api      = api
-        @location = location
+      # @param [Boolean] incubator Return experimental extractions
+      #
+      def initialize(api, location, incubator = false)
+        @api       = api
+        @location  = location
+        @incubator = incubator
+        @req_opts  = {}
+
+        if incubator
+          @req_opts = { headers: @api.version_header(:json, :incubator) }
+        end
 
         update
       end
@@ -21,7 +29,7 @@ module Gini
       # Populate instance variables from fetched extractions
       #
       def update
-        response = @api.request(:get, @location)
+        response = @api.request(:get, @location, @req_opts)
 
         unless response.status == 200
           raise Gini::Api::DocumentError.new(
@@ -33,6 +41,14 @@ module Gini
         # Entire response
         @raw = response.parsed
 
+        # raise exception if parsing failed
+        if response.parsed.nil?
+          raise Gini::Api::DocumentError.new(
+            "Failed to parse extractions from #{@location}",
+            response
+          )
+        end
+
         response.parsed[:extractions].each do |k,v|
           instance_variable_set("@#{k}", v)
         end

data/lib/gini-api/oauth.rb

@@ -28,6 +28,7 @@ module Gini
           token_url: '/oauth/token',
           max_redirects: 0,
           raise_errors: true,
+          connection_opts: { headers: { user_agent: api.user_agent } }
         )
 
         # Verify opts. Prefered authorization methis is auth_code. If no auth_code is present a login from

data/lib/gini-api/version.rb

@@ -1,6 +1,6 @@
 module Gini
   module Api
     # Package version
-    VERSION = "0.9.9"
+    VERSION = '0.9.10'
   end
 end

data/spec/gini-api/client_spec.rb

@@ -58,6 +58,11 @@ describe Gini::Api::Client do
         include(:gini_xml)
     end
 
+    it do
+      expect(OAuth2::Response::PARSERS.keys).to \
+        include(:gini_incubator)
+    end
+
   end
 
   describe '#login' do
@@ -140,6 +145,15 @@ describe Gini::Api::Client do
 
     end
 
+    context 'with incubator' do
+
+      it 'returns accept header with incubator version' do
+        expect(api.version_header(:json, :incubator)).to \
+          eql({ accept: 'application/vnd.gini.incubator+json' })
+      end
+
+    end
+
   end
 
   context 'being logged in' do
@@ -223,6 +237,24 @@ describe Gini::Api::Client do
 
       end
 
+      context 'return JSON on incubator request' do
+
+        let(:header) { 'application/vnd.gini.incubator+json' }
+        let(:body)   {
+          {
+            a: 1,
+            b: 2
+          }.to_json
+        }
+
+        it do
+          expect(api.token).to \
+            receive(:get).and_return(OAuth2::Response.new(response))
+          expect(api.request(:get, '/dummy').parsed).to be_a Hash
+        end
+
+      end
+
       context 'set custom accept header' do
 
         let(:header) { 'application/octet-stream' }

data/spec/gini-api/document/extraction_spec.rb

@@ -33,8 +33,9 @@ describe Gini::Api::Document::Extractions do
     )
   end
 
-  let(:header)   { 'application/vnd.gini.v1+json' }
-  let(:location) { 'https://api.gini.net/document/aaa-bbb-ccc/extractions' }
+  let(:incubator) { false }
+  let(:header)    { 'application/vnd.gini.v1+json' }
+  let(:location)  { 'https://api.gini.net/document/aaa-bbb-ccc/extractions' }
   let(:response) do
     double('Response',
       status: 200,
@@ -68,7 +69,7 @@ describe Gini::Api::Document::Extractions do
     )
   end
 
-  subject(:extractions) { Gini::Api::Document::Extractions.new(api, location) }
+  subject(:extractions) { Gini::Api::Document::Extractions.new(api, location, incubator) }
 
   it { should respond_to(:update) }
   it { should respond_to(:[]) }
@@ -98,6 +99,44 @@ describe Gini::Api::Document::Extractions do
 
     end
 
+    context 'failed to parse response' do
+
+      let(:response) do
+        double('Response',
+          status: 200,
+          headers: {
+            'content-type' => 'vnd/gini.not.supported+json'
+          },
+          env: {},
+          body: {}.to_json
+        )
+      end
+
+      it 'raises exception' do
+        expect { extractions.update }.to \
+          raise_error(Gini::Api::DocumentError, /Failed to parse extractions from #{location}/)
+      end
+
+    end
+
+    context 'with incubator=true' do
+
+      let(:extractions) { Gini::Api::Document::Extractions.new(api, location, incubator=true) }
+
+      it do
+        expect(api.token).to receive(:get).with(
+          location,
+          {
+            headers: {
+              accept: 'application/vnd.gini.incubator+json'
+            }
+          }
+        ).and_return(OAuth2::Response.new(response))
+        expect(extractions.instance_variable_get(:@req_opts)).to eql({ headers: { accept: 'application/vnd.gini.incubator+json' } })
+      end
+
+    end
+
   end
 
   describe '#[]' do

data/spec/gini-api/document_spec.rb

@@ -32,6 +32,7 @@ describe Gini::Api::Document do
         b: 2,
         progress: 'PENDING',
         _links: {
+          document: location,
           extractions: "#{location}/extractions",
           layout: "#{location}/layout",
           processed: "#{location}/processed"
@@ -50,6 +51,7 @@ describe Gini::Api::Document do
   it { should respond_to(:pages) }
   it { should respond_to(:completed?) }
   it { should respond_to(:successful?) }
+  it { should respond_to(:report_error) }
 
   it 'does accept duration' do
     expect(document.duration).to be_nil
@@ -368,4 +370,54 @@ describe Gini::Api::Document do
 
   end
 
+  describe '#report_error' do
+
+    let(:report_response) do
+      double('Response', {
+        status: 200,
+        headers: { 'content-type' => header },
+        body: {
+          message: "error was reported, please refer to the given error id",
+          errorId: "deadbeef-dead-dead-beef-deadbeeeeef",
+        }.to_json
+      })
+    end
+
+    context 'succeeds and returns error id' do
+
+      it do
+        expect(api.token).to receive(:post).with(
+          "#{location}/errorreport",
+          {
+            headers: { accept: header },
+            params: { summary: nil, description: nil }
+          }
+        ).and_return(OAuth2::Response.new(report_response))
+
+        expect(document.report_error()).to eql("deadbeef-dead-dead-beef-deadbeeeeef")
+      end
+
+    end
+
+    context 'fails and raises exception' do
+
+      let(:report_response) { double('Response', status: 404, body: {}, env: {}) }
+
+      it do
+        expect(api.token).to receive(:post).with(
+          "#{location}/errorreport",
+          {
+            headers: { accept: header },
+            params: { summary: nil, description: nil }
+          }
+        ).and_return(OAuth2::Response.new(report_response))
+
+        expect { document.report_error() }.to \
+          raise_error(Gini::Api::DocumentError, /Failed to submit error report for document/)
+      end
+
+    end
+
+  end
+
 end

data/spec/gini-api/oauth_spec.rb

@@ -18,7 +18,8 @@ describe Gini::Api::OAuth do
       client_id: 'cid',
       client_secret: 'sec',
       oauth_site: oauth_site,
-      oauth_redirect: redirect
+      oauth_redirect: redirect,
+      user_agent: 'gini-api-ruby/spec'
     )
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gini-api
 version: !ruby/object:Gem::Version
-  version: 0.9.9
+  version: 0.9.10
 platform: ruby
 authors:
 - Daniel Kerwin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-09 00:00:00.000000000 Z
+date: 2015-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2