gini-api 0.9.2

data/lib/gini-api/client.rb

@@ -0,0 +1,284 @@
+require 'uri'
+require 'json'
+require 'logger'
+require 'faraday'
+require 'benchmark'
+
+module Gini
+  module Api
+
+    # Main class to operate on the Gini API
+    #
+    class Client
+
+      attr_reader :token, :log
+
+      # Instantiate a new Gini::Api::Client object with OAuth capabilities
+      #
+      # @param [Hash] options Hash of available config settings
+      # @option options [String]  :client_id OAuth client_id
+      # @option options [String]  :client_secret OAuth client_secret
+      # @option options [String]  :oauth_site OAuth site to connect to (https://user.gini.net)
+      # @option options [String]  :oauth_redirect Redirect URI
+      # @option options [Integer] :upload_timeout Upload timeout in seconds
+      # @option options [Integer] :processing_timeout API operational timeout in seconds
+      # @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)
+      #
+      # @example
+      #   api = Gini::Api::Client.new(
+      #     client_id: 'my_client_id',
+      #     client_secret: 'my_client_secret',
+      #   )
+      #
+      def initialize(options = {})
+        opts = {
+          oauth_site: 'https://user.gini.net/',
+          oauth_redirect: 'http://localhost',
+          api_uri: 'https://api.gini.net',
+          api_version: 'v1',
+          api_type: 'json',
+          upload_timeout: 90,
+          processing_timeout: 180,
+          log: Logger.new(STDOUT),
+        }.merge(options)
+
+        # Ensure mandatory keys are set
+        [:client_id, :client_secret].each do |k|
+          raise Gini::Api::Error.new("Mandatory option key is missing: #{k}") unless opts.key?(k)
+        end
+
+        # Populate instance variables from merged opts
+        opts.each do |k, v|
+          instance_variable_set("@#{k}", v)
+          self.class.send(:attr_reader, k)
+        end
+
+        # Ensure STDOUT is flushed
+        STDOUT.sync = true
+
+        # Sanitize api_uri
+        @api_uri.sub!(/(\/)+$/, '')
+
+        # Create upload connection
+        @upload_connection = Faraday.new(url: @api_uri) do |builder|
+          builder.use(Faraday::Request::Multipart)
+          builder.use(Faraday::Request::UrlEncoded)
+          builder.request(:retry, 3)
+          builder.adapter(Faraday.default_adapter)
+        end
+
+        # Register parser (json+xml) based on API version
+        register_parser
+
+        @log.info('Gini API client initialized')
+        @log.info("Target: #{@api_uri}")
+      end
+
+      # Register OAuth2 response parser
+      #
+      def register_parser
+        OAuth2::Response.register_parser(:gini_json, [version_header(:json)[:accept]]) do |body|
+          MultiJson.load(body, symbolize_keys: true) rescue body
+        end
+        OAuth2::Response.register_parser(:gini_xml, [version_header(:xml)[:accept]]) do |body|
+          MultiXml.parse(body) rescue body
+        end
+      end
+
+      # Acquire OAuth2 token and popolate @oauth (instance of Gini::Api::OAuth.new)
+      # and @token (OAuth2::AccessToken).  Supports 2 strategies: username/password and authorization code
+      #
+      # @param [Hash] opts Your authorization credentials
+      # @option opts [String] :auth_code OAuth authorization code. Will be exchanged for a token
+      # @option opts [String] :username API username
+      # @option opts [String] :password API password
+      #
+      # @example
+      #   api.login(auth_code: '1234567890')
+      # @example
+      #   api.login(username: 'me@example.com', password: 'secret')
+      #
+      def login(opts)
+        @oauth = Gini::Api::OAuth.new(self, opts)
+        @token = @oauth.token
+      end
+
+      # Destroy OAuth2 token
+      #
+      def logout
+        @oauth.destroy
+      end
+
+      # Version accept header based on @api_version
+      #
+      # @param [Symbol, String] type Expected response type (:xml, :json)
+      #
+      # @return [Hash] Return accept header or empty hash
+      #
+      def version_header(type = @api_type)
+        { accept: "application/vnd.gini.#{@api_version}+#{type}" }
+      end
+
+      # Request wrapper that sets URI and accept header
+      #
+      # @param [Symbol] verb     HTTP request verb (:get, :post, :put, :delete)
+      # @param [String] resource API resource like /documents
+      # @param [Hash]   options  Optional type and custom headers
+      # @option options [String] :type Type to pass to version_header (:xml, :json)
+      # @option options [Hash]   :headers Custom headers. Must include accept
+      #
+      def request(verb, resource, options = {})
+        opts = {
+          headers: version_header(options.delete(:type) || @api_type)
+        }.merge(options)
+
+        timeout(@processing_timeout) do
+          @token.send(verb.to_sym, @api_uri + URI.parse(resource).path, opts)
+        end
+      rescue OAuth2::Error => e
+        raise Gini::Api::RequestError.new(
+          "API request failed: #{verb} #{resource} (code=#{e.response.status})",
+          e.response
+        )
+      rescue Timeout::Error => e
+        raise Gini::Api::ProcessingError.new(
+          "API request timed out: #{verb} #{resource} (#{e.message})"
+        )
+      end
+
+      # Upload a document
+      #
+      # @param [String] file path of the document to upload
+      #
+      # @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 and monitor progress
+      #   doc = api.upload('/tmp/myfile.pdf') { |d| puts "Progress: #{d.progress}" }
+      #
+      def upload(file, &block)
+        @log.info("Uploading #{file}")
+
+        duration = {}
+
+        # Document upload
+        duration[:upload] = Benchmark.realtime do
+          @response = @upload_connection.post do |req|
+            req.options[:timeout] = @upload_timeout
+            req.url 'documents/'
+            req.headers['Content-Type']  = 'multipart/form-data'
+            req.headers['Authorization'] = "Bearer #{@token.token}"
+            req.headers.merge!(version_header)
+            req.body = { file: Faraday::UploadIO.new(file, 'application/octet-stream') }
+          end
+        end
+
+        # Start polling (0.5s) when document has been uploaded successfully
+        if @response.status == 201
+          location = @response.headers['location']
+          doc = Gini::Api::Document.new(self, location)
+          begin
+            timeout(@processing_timeout) do
+              duration[:processing] = Benchmark.realtime do
+                doc.poll(&block)
+              end
+            end
+          rescue Timeout::Error => e
+            ex = Gini::Api::ProcessingError.new(e.message)
+            ex.docid = doc.id
+            raise ex
+          end
+        else
+          raise Gini::Api::UploadError.new(
+            "Document upload failed with HTTP code #{@response.status}",
+            @response
+          )
+        end
+
+        # Combine duration values and update doc object
+        duration[:total] = duration[:upload] + duration[:processing]
+        doc.duration = duration
+
+        doc
+      end
+
+      # Delete document
+      #
+      # @param [String] id document ID
+      #
+      def delete(id)
+        response = request(:delete, "/documents/#{id}")
+        unless response.status == 204
+          raise Gini::Api::DocumentError.new(
+            "Deletion of docId #{id} failed (code=#{response.status})",
+            response
+          )
+        end
+        @log.info("Deleted document #{id}")
+      end
+
+      # Get document by Id
+      #
+      # @param [String] id document ID
+      #
+      # @return [Gini::Api::Document] Return Gini::Api::Document object
+      #
+      def get(id)
+        Gini::Api::Document.new(self, "/documents/#{id}")
+      end
+
+      # List all documents
+      #
+      # @param [Hash] options List options (offset and limit)
+      # @option options [Integer] :limit Maximum number of documents to return (defaults to 20)
+      # @option options [Integer] :offset Start offset. Defaults to 0
+      #
+      # @return [Gini::Api::DocumentSet] Returns a DocumentSet with total, offset and a list of Document objects
+      #
+      def list(options = {})
+        opts   = { limit: 20, offset: 0 }.merge(options)
+        limit  = Integer(opts[:limit])
+        offset = Integer(opts[:offset])
+
+        response = request(:get, "/documents?limit=#{limit}&next=#{offset}")
+        unless response.status == 200
+          raise Gini::Api::DocumentError.new(
+            "Failed to get list of documents (code=#{response.status})",
+            response
+          )
+        end
+        Gini::Api::DocumentSet.new(self, response.parsed)
+      end
+
+      # Fulltext search for documents
+      #
+      # @param [String, Array] query  The search term(s), separated by space. Multiple terms as array
+      # @param [Hash] options Search options
+      # @option options [String]  :type   Only include documents with the given doctype
+      # @option options [Integer] :limit  Number of results per page. Must be between 1 and 250. Defaults to 20
+      # @option options Integer]  :offset Start offset. Defaults to 0
+      #
+      # @return [Gini::Api::DocumentSet] Returns a DocumentSet with total, offset and a list of Document objects
+      #
+      def search(query, options = {})
+        opts   = { type: '', limit: 20, offset: 0 }.merge(options)
+        query  = URI.escape(query)
+        type   = URI.escape(opts[:type])
+        limit  = Integer(opts[:limit])
+        offset = Integer(opts[:offset])
+
+        response = request(:get, "/search?q=#{query}&type=#{type}&limit=#{limit}&next=#{offset}")
+        unless response.status == 200
+          raise Gini::Api::SearchError.new(
+            "Search query failed with code #{response.status}",
+            response
+          )
+        end
+        Gini::Api::DocumentSet.new(self, response.parsed)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Gini
+  module Api
+
+    # Contains document related extractions
+    #
+    class Document::Extractions
+
+      attr_reader :raw
+
+      # Instantiate a new Gini::Api::Extractions object from hash
+      #
+      # @param [Gini::Api::Client] api Gini::Api::Client object
+      # @param [String] location Document URL
+      def initialize(api, location)
+        @api      = api
+        @location = location
+
+        update
+      end
+
+      # Populate instance variables from fetched extractions
+      #
+      def update
+        response = @api.request(:get, @location)
+
+        unless response.status == 200
+          raise Gini::Api::DocumentError.new(
+            "Failed to fetch extractions from #{@location}",
+            response
+          )
+        end
+
+        # Entire response
+        @raw = response.parsed
+
+        response.parsed[:extractions].each do |k,v|
+          instance_variable_set("@#{k}", v)
+          self.class.send(:attr_reader, k)
+        end
+
+        instance_variable_set("@candidates", response.parsed[:candidates])
+        self.class.send(:attr_reader, :candidates)
+      end
+
+      # Get filed value for given extraction key
+      #
+      # @param [String] item The extractions item to get the value of
+      # @return [String, Integer] Returns the value from extractions hash
+      #
+      def [](item)
+        unless instance_variable_get("@#{item}")
+          raise Gini::Api::DocumentError.new("Invalid extraction key #{item}: Not found")
+        end
+
+        instance_variable_get("@#{item}")[:value]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Gini
+  module Api
+
+    # Contains document layout in XML & JSON
+    #
+    class Document::Layout
+
+      # Instantiate a new Gini::Api::Layout object from layout url
+      #
+      # @param [Gini::Api::Client] api Gini::Api::Client object
+      # @param [String] location Document URL
+      def initialize(api, location)
+        @api      = api
+        @location = location
+      end
+
+      # Return layout as XML string
+      #
+      # @return [String] Returns the layout as XML string
+      def to_xml
+        @xml ||= get_xml
+      end
+
+      # Return layout as JSON string
+      #
+      # @return [String] Returns the layout as JSON string
+      def to_json
+        @json ||= get_json
+      end
+
+      private
+
+      # Get value of layout in XML
+      #
+      # @return [String] Returns layout XML
+      def get_xml
+        response = @api.request(:get, @location, type: 'xml')
+        response.body if response.status == 200
+      end
+
+      # Get value of extraction. Convinience method
+      #
+      # @return [String] Returns layout JSON
+      def get_json
+        response = @api.request(:get, @location)
+        response.body if response.status == 200
+      end
+    end
+  end
+end

data/lib/gini-api/document.rb

@@ -0,0 +1,136 @@
+require 'eventmachine'
+
+module Gini
+  module Api
+
+    # Contains document related data from uploaded or fetched document
+    #
+    class Document
+
+      attr_accessor :duration
+
+      # Instantiate a new Gini::Api::Document object from URL
+      #
+      # @param [Gini::Api::Client] api       Gini::Api::Client object
+      # @param [String]            location  Document URL
+      # @param [Hash]              from_data Hash with doc data (from search for example)
+      #
+      def initialize(api, location, from_data = nil)
+        @api      = api
+        @location = location
+
+        update(from_data)
+      end
+
+      # Fetch document resource and populate instance variables
+      #
+      # @param [Hash] from_data Ruby hash with doc data
+      #
+      def update(from_data = nil)
+        data = {}
+
+        if from_data.nil?
+          response = @api.request(:get, @location)
+          unless response.status == 200
+            raise Gini::Api::DocumentError.new(
+              "Failed to fetch document data (code=#{response.status})",
+              response
+            )
+          end
+          data = response.parsed
+        else
+          data = from_data
+        end
+
+        data.each do |k, v|
+          instance_variable_set("@#{k}", v)
+
+          # We skip pages as it's rewritted by method pages()
+          next if k == :pages
+
+          self.class.send(:attr_reader, k)
+        end
+      end
+
+      # Poll document progress and return when state equals COMPLETED
+      # Known states are PENDING, COMPLETED and ERROR
+      #
+      # @param [Float] interval API polling interval
+      #
+      def poll(interval = 0.5)
+        EM.run do
+          EM.add_periodic_timer(interval) do
+            update
+            EM.stop if @progress =~ /(COMPLETED|ERROR)/
+            yield self if block_given?
+          end
+        end
+      end
+
+      # Get processed document
+      #
+      # @return [data] The binary representation of the processed document (pdf, jpg, png, ...)
+      #
+      def processed
+        response = @api.request(
+          :get,
+          @_links[:processed],
+          headers: { accept: 'application/octet-stream' }
+        )
+        unless response.status == 200
+          raise Gini::Api::DocumentError.new(
+            "Failed to fetch processed document (code=#{response.status})",
+            response
+          )
+        end
+        response.body
+      end
+
+      # Initialize extractions from @_links and return Gini::Api::Extractions object
+      #
+      # @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])
+      end
+
+      # Initialize layout from @_links[:layout] and return Gini::Api::Layout object
+      #
+      # @return [Gini::Api::Document::Layout] Return Gini::Api::Document::Layout object for uploaded document
+      #
+      def layout
+        @layout ||= Gini::Api::Document::Layout.new(@api, @_links[:layout])
+      end
+
+      # Override @pages instance variable. Removes key :pageNumber, key :images and starts by index 0.
+      # Page 1 becomes index 0
+      #
+      def pages
+        @pages.map { |page| page[:images] }
+      end
+
+      # Submit feedback on extraction label
+      #
+      # @param [String] label Extraction label to submit feedback on
+      # @param [String] value The new value for the given label
+      #
+      def submit_feedback(label, value)
+        unless extractions.send(label.to_sym)
+          raise Gini::Api::DocumentError.new("Unknown label #{label}: Not found")
+        end
+        response = @api.request(
+          :put,
+          "#{@_links[:extractions]}/#{label}",
+          headers: { 'content-type' => @api.version_header[:accept] },
+          body: { value: value }.to_json
+        )
+        unless response.status == 204
+          raise Gini::Api::DocumentError.new(
+            "Failed to submit feedback for label #{label} (code=#{response.status})",
+            response
+          )
+        end
+      end
+    end
+  end
+end

data/lib/gini-api/documentset.rb

@@ -0,0 +1,35 @@
+module Gini
+  module Api
+
+    # Set of documents resulting from search or list query
+    #
+    class DocumentSet
+
+      attr_reader :total, :offset, :documents
+
+      # Enumerable mixin
+      include Enumerable
+
+      # Instantiate a new Gini::Api::Document object from URL
+      #
+      # @param [Gini::Api::Client]    api        Gini::Api::Client object
+      # @param [Hash]                 data       Container for documents
+      # @option data [Integer]        :totalCount Total number of documents
+      # @option data [Aarray]         :documents  List of documents including all data
+      #
+      def initialize(api, data)
+        @total     = data[:totalCount]
+        @documents = data[:documents].map do |doc|
+          Gini::Api::Document.new(api, doc[:_links][:document], doc)
+        end
+      end
+
+      # Allow iteration on documents by yielding documents
+      # Required by Enumerable mixin
+      #
+      def each
+        @documents.each { |d| yield(d) }
+      end
+    end
+  end
+end

data/lib/gini-api/error.rb

@@ -0,0 +1,100 @@
+module Gini
+  module Api
+
+    # Base api exception class
+    #
+    # @!attribute [r] api_response
+    #   @return [Faraday::Response] Faraday response object
+    # @!attribute [r] api_method
+    #   @return [String] HTTP method (:get, :post, :put, :delete)
+    # @!attribute [r] api_url
+    #   @return [String] Request URL
+    # @!attribute [r] api_status
+    #   @return [Integer] HTTP status code
+    # @!attribute [r] api_message
+    #   @return [String] Message from API error object
+    #   @see http://developer.gini.net/gini-api/html/overview.html#client-errors
+    # @!attribute [r] api_reqid
+    #   @return [String] Request id from API error object
+    #   @see http://developer.gini.net/gini-api/html/overview.html#client-errors
+    # @!attribute [r] docid
+    #   @return [String] Optional document-id that caused the exception
+    #
+    class Error < StandardError
+      attr_reader   :api_response, :api_method, :api_url
+      attr_reader   :api_status, :api_message, :api_request_id
+      attr_accessor :docid
+
+      # Parse response object and set instance vars accordingly
+      #
+      # @param [String] msg Exception message
+      # @param [OAuth2::Response] api_response Faraday/Oauth2 response object from API
+      #
+      def initialize(msg, api_response = nil)
+        super(msg)
+
+        # Automatically use included response object if possible
+        @api_response = api_response.respond_to?(:response) ? api_response.response : api_response
+
+        # Parse response and set instance vars
+        parse_response unless @api_response.nil?
+      end
+
+      # Build api error message rom api response
+      #
+      def api_error
+        return nil if @api_response.nil?
+
+        m =  "#{@api_method.to_s.upcase} "
+        m << "#{@api_url} : "
+        m << "#{@api_status} - "
+        m << "#{@api_message} (request Id: #{@api_request_id})"
+        m
+      end
+
+      # Parse Faraday response and fill instance variables
+      #
+      def parse_response
+        @api_method     = @api_response.env[:method]
+        @api_url        = @api_response.env[:url].to_s
+        @api_status     = @api_response.status
+        @api_message    = 'undef'
+        @api_request_id = 'undef'
+
+        unless @api_response.body.empty?
+          begin
+            parsed = JSON.parse(@api_response.body, symbolize_names: true)
+            @api_message    = parsed[:message]
+            @api_request_id = parsed[:requestId]
+          rescue JSON::ParserError
+            # We fail silently as defaults have been set
+          end
+        end
+      end
+    end
+
+    # OAuth related errors
+    #
+    OAuthError = Class.new(Error)
+
+    # Document related errors
+    #
+    DocumentError = Class.new(Error)
+
+    # Upload related errors
+    #
+    UploadError = Class.new(Error)
+
+    # Processing related errors
+    #
+    ProcessingError = Class.new(Error)
+
+    # Search related errors
+    #
+    SearchError = Class.new(Error)
+
+    # Generic request errors
+    #
+    RequestError = Class.new(Error)
+  end
+end