gini-api 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 3e0a78fff7ea84fe5f7124e103861964da618830
4
+ data.tar.gz: 5b381a2a131e6e117f94628b37f45e8b521c3b38
5
+ SHA512:
6
+ metadata.gz: 94f60834223b3afdedee4ef203416b48869029eb1a61b077466026866589ed2cd95226bbeb6d9c3db13ac42dff16594227fb553483c4f2825e8d6407da221e5f
7
+ data.tar.gz: 4afccb044306250c91d10b8e3cc64947f10aeada8cc72a6df41499ed67f294aaba60003c7e97ae0f1efe8a6e3d3fd6bfb145c976768c863c4d7a6f29f6906b9f
data/.gitignore ADDED
@@ -0,0 +1,7 @@
1
+ coverage
2
+ doc
3
+ pkg
4
+ vendor
5
+ spec/reports
6
+ .yardoc
7
+ Gemfile.lock
data/.rspec ADDED
@@ -0,0 +1,2 @@
1
+ --color
2
+ --order random
data/.travis.yml ADDED
@@ -0,0 +1,5 @@
1
+ language: ruby
2
+ rvm:
3
+ - 1.9.3
4
+ - 2.0.0
5
+ - 2.1.0
data/Gemfile ADDED
@@ -0,0 +1,3 @@
1
+ source 'https://rubygems.org'
2
+
3
+ gemspec
data/Guardfile ADDED
@@ -0,0 +1,4 @@
1
+ guard :rspec, run_all: { cmd: 'rspec -P "spec/gini-api/**/*_spec.rb"' }, all_after_pass: true do
2
+ watch(%r{^spec/.+_spec\.rb$})
3
+ watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
4
+ end
data/README.md ADDED
@@ -0,0 +1,298 @@
1
+ <img src="https://www.gini.net/wp-content/uploads/2014/02/Gini-API_logo.svg" width="222" alt="Gini API logo" />
2
+
3
+ # Gini API Ruby client
4
+
5
+ [![Build Status](https://travis-ci.org/gini/gini-api-ruby.png)](https://travis-ci.org/gini/gini-api-ruby)
6
+ [![Code Climate](https://codeclimate.com/github/gini/gini-api-ruby.png)](https://codeclimate.com/github/gini/gini-api-ruby)
7
+ [![Coverage Status](https://coveralls.io/repos/gini/gini-api-ruby/badge.png)](https://coveralls.io/r/gini/gini-api-ruby)
8
+ [![Gem Version](https://badge.fury.io/rb/gini-api-ruby.png)](http://badge.fury.io/rb/gini-api-ruby)
9
+
10
+ ## Resources
11
+
12
+ - Gini API overview: [https://www.gini.net/api/](https://www.gini.net/api/)
13
+ - Gini API documentation: [http://developer.gini.net/gini-api/](http://developer.gini.net/gini-api/)
14
+ - Issue tracker: [https://github.com/gini/gini-api-ruby/issues](https://github.com/gini/gini-api-ruby/issues)
15
+
16
+ ## Installation
17
+
18
+ ```
19
+ gem install gini-api
20
+ ```
21
+
22
+ ## Usage examples
23
+
24
+ Some code snippets to explain the usage of the API client. Please refer to the docs for a complete list of available classes and methods.
25
+
26
+ ### Initialize API object and setup authorization
27
+
28
+ gini-api-ruby supports two authentication mechanisms:
29
+
30
+ - authentication code
31
+ - username/password
32
+
33
+ If you are planning to integrate gini-api-ruby into your ruby it is highly recommended to acquire the auth_code yourself and pass it to the login method.
34
+ The authentication flow is described in detail in the official [API docs](http://developer.gini.net/gini-api/html/guides/oauth2.html#server-side-flow).
35
+
36
+ ```ruby
37
+ require 'gini-api'
38
+
39
+ api = Gini::Api::Client.new(
40
+ client_id: 'my_client_id',
41
+ client_secret: 'my_client_secret'
42
+ )
43
+
44
+ # auth_code (has been extracted outside of gini-api-ruby)
45
+ api.login('1234567890')
46
+
47
+ # username/password
48
+ api.login('user@example.com', 'password')
49
+ ```
50
+
51
+ ### Upload
52
+
53
+ ```ruby
54
+ doc = api.upload('/tmp/my_doc.pdf')
55
+ # => Gini::Api::Document
56
+ doc.id
57
+ # => "123456789-abcd-ef12-000000000000"
58
+ doc.progress
59
+ # => "COMPLETED"
60
+ ```
61
+
62
+ ### List
63
+
64
+ ```ruby
65
+ list = api.list(limit: 20)
66
+ # => Gini::Api::DocumentSet
67
+ list.total
68
+ # => 15
69
+ list.documents
70
+ # => [Gini::Api::Document, Gini::Api::Document, ...]
71
+ list.each do { |doc| puts doc.id }
72
+ # => 1234567890-abc, 0987654321-cba, ...
73
+ ```
74
+
75
+ ### Get
76
+
77
+ ```ruby
78
+ doc = api.get('123456789-abcd-ef12-000000000000')
79
+ # => Gini::Api::Document
80
+ doc.name
81
+ # => test.pdf
82
+ ```
83
+
84
+ ### Delete
85
+
86
+ ```ruby
87
+ api.delete('123456789-abcd-ef12-000000000000')
88
+ # => true
89
+ ```
90
+
91
+ ### Search
92
+
93
+ ```ruby
94
+ search = api.search('Telekom', type: 'invoice')
95
+ # => Gini::Api::DocumentSet
96
+ search.total
97
+ # => 5
98
+ search.documents
99
+ # => [Gini::Api::Document, Gini::Api::Document, ...]
100
+ search.each do { |doc| puts doc.id }
101
+ # => 1234567890-abc, 0987654321-cba, ...
102
+ ```
103
+
104
+ ### Pages
105
+
106
+ ```ruby
107
+ doc = api.get('123456789-abcd-ef12-000000000000')
108
+ # => Gini::Api::Document
109
+ doc.pages.length
110
+ # => 1
111
+ doc.pages[0][:'1280x1810']
112
+ # => "https://api.gini.net/documents/123456789-abcd-ef12-000000000000/pages/1/1280x1810"
113
+ ```
114
+
115
+ ### Layout
116
+
117
+ ```ruby
118
+ doc.layout.to_json
119
+ # => JSON string
120
+ doc.layout.to_xml
121
+ # => XML string
122
+ ```
123
+
124
+ ### Document source
125
+
126
+ Optimized document after it has been processed (`deskewed`, `optimized`, ...).
127
+
128
+ ```ruby
129
+ File.open('/tmp/processed_file.pdf', 'w') { |f| f.write(doc.processed) }
130
+ ```
131
+
132
+ ### Extractions
133
+
134
+ ```ruby
135
+ doc.extractions.amountToPay
136
+ # => {:entity=>"amount", :value=>"10.00:EUR", :box=>{:top=>2176.0, :left=>2000.0, :width=>173.0, :height=>50.0, :page=>1}, :candidates=>"amounts"}
137
+ doc.extractions[:amountToPay] # Shortcut to get extraction value
138
+ # => "10.00:EUR"
139
+ doc.extractions.candidates[:dates]
140
+ # => Array of all found candidates
141
+ doc.extractions.raw
142
+ # => {:extractions=>{...
143
+ ```
144
+
145
+ ### Submitting feedback
146
+
147
+ ```ruby
148
+ doc.submit_feedback(:bic, 'XXXXXXXX')
149
+ # => nil
150
+ doc.submit_feedback(:unknownlabel, 'XXXXXXX')
151
+ # => raises Gini::Api::DocumentError
152
+ ```
153
+
154
+ ## Exceptions / Error handling
155
+
156
+ A set of custom exceptions is available if API operations fail to complete. In most cases the raised exception objects contain additional information in instance variables prefixed `api_`. Eg:
157
+
158
+ ```ruby
159
+ begin
160
+ api.login('user@example.com', 'invalid_password')
161
+ rescue Gini::Api::OAuthError => e
162
+ puts e.message
163
+ # => Error message supplied when exception was raised
164
+ puts e.api_error
165
+ # => POST https://api.gini.net/documents/abc-123 : 500 - ERROR_MESSAGE (reqId: OPTIONAL_REQUEST_ID)
166
+ puts e.api_status
167
+ # => 500
168
+ puts e.api_url
169
+ # => https://api.gini.net/documents/abc-123
170
+ puts e.method
171
+ # => POST
172
+ puts e.api_message
173
+ # => ERROR MESSAGE
174
+ puts e.api_request_id
175
+ # => OPTIONAL_REQUEST_ID
176
+ end
177
+ ```
178
+
179
+ 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](Gini/Api/Error.html).
180
+
181
+ ## Developers
182
+
183
+ ### Getting started
184
+
185
+ ```
186
+ git clone https://github.com/gini/gini-api-ruby.git
187
+ cd gini-api-ruby
188
+ bundle
189
+ rake -T
190
+ ```
191
+
192
+ ### Contributing
193
+
194
+ It's awesome that you consider contributing to gini-api-ruby. Here's how it's done:
195
+
196
+ 1. Fork repository on [Github](https://github.com/gini/gini-api-ruby)
197
+ 2. Create a topic/feature branch
198
+ 3. Write code AND tests
199
+ 4. Update documentation if necessary
200
+ 5. Open a pull request
201
+
202
+ ### Generate local documentation
203
+
204
+ ```
205
+ rake yard
206
+ Files: 10
207
+ Modules: 3 ( 0 undocumented)
208
+ Classes: 12 ( 0 undocumented)
209
+ Constants: 2 ( 0 undocumented)
210
+ Methods: 29 ( 0 undocumented)
211
+ 100.00% documented
212
+
213
+ open doc/index.html
214
+ ```
215
+
216
+ ### Tests
217
+
218
+ The tests are divided into unit and integration tests. The integration tests will contact the 'real' API service and trigger specific actions.
219
+
220
+ #### Unit tests
221
+
222
+ ```
223
+ rake spec:unit
224
+ /Users/dkerwin/.rvm/rubies/ruby-2.0.0-p195/bin/ruby -S rspec spec/gini-api/client_spec.rb spec/gini-api/document/extraction_spec.rb
225
+ spec/gini-api/document/layout_spec.rb spec/gini-api/document_spec.rb spec/gini-api/error_spec.rb spec/gini-api/oauth_spec.rb
226
+ ......................................................................
227
+
228
+ Finished in 0.12666 seconds
229
+ 70 examples, 0 failures
230
+ ```
231
+
232
+ #### Integration tests
233
+
234
+ Please note that you must specify you API credentials as environment variables.
235
+
236
+ ```
237
+ GINI_CLIENT_ID=***** GINI_CLIENT_SECRET=***** GINI_API_USER=***** GINI_API_PASS=***** rake spec:integration
238
+ /Users/dkerwin/.rvm/rubies/ruby-2.0.0-p195/bin/ruby -S rspec spec/integration/api_spec.rb
239
+ ..........
240
+
241
+ Finished in 31.3 seconds
242
+ 13 examples, 0 failures, 0 pending
243
+ ```
244
+
245
+ #### All-in-one
246
+
247
+ ```
248
+ GINI_CLIENT_ID=***** GINI_CLIENT_SECRET=***** GINI_API_USER=***** GINI_API_PASS=***** rake spec:all
249
+ ```
250
+
251
+ #### Code coverage
252
+
253
+ Code coverage reports are automatically created. The reports can be found in `coverage/`.
254
+
255
+ ```
256
+ rake spec:unit
257
+ ..............................................................................................................
258
+
259
+ Finished in 0.79855 seconds
260
+ 110 examples, 0 failures
261
+
262
+ Randomized with seed 49394
263
+
264
+ Coverage report generated for RSpec to xxx/Code/gini-api-ruby/coverage. 274 / 274 LOC (100.0%) covered.
265
+ Coverage report Rcov style generated for RSpec to xxx/Code/gini-api-ruby/coverage/rcov
266
+ ```
267
+
268
+ #### Continous Integration
269
+
270
+ It's possible to create jUnit compatible test reports that can be used by tools like [Jenkins](http://jenkins-ci.org/). The generated XML files can be found in `spec/reports`. Simply modify your rake call:
271
+
272
+ ```
273
+ rake ci:setup:rspec spec:all
274
+ ```
275
+
276
+ ## License
277
+
278
+ The MIT License (MIT)
279
+
280
+ Copyright (c) 2014 Gini GmbH
281
+
282
+ Permission is hereby granted, free of charge, to any person obtaining a copy
283
+ of this software and associated documentation files (the "Software"), to deal
284
+ in the Software without restriction, including without limitation the rights
285
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
286
+ copies of the Software, and to permit persons to whom the Software is
287
+ furnished to do so, subject to the following conditions:
288
+
289
+ The above copyright notice and this permission notice shall be included in all
290
+ copies or substantial portions of the Software.
291
+
292
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
293
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
294
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
295
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
296
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
297
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
298
+ SOFTWARE.
data/Rakefile ADDED
@@ -0,0 +1,48 @@
1
+ require 'bundler/gem_tasks'
2
+ require 'rake/clean'
3
+
4
+ CLEAN << FileList['pkg', '*.gem']
5
+
6
+ task :test => :'spec:unit'
7
+ task :default => :'spec:unit'
8
+
9
+ ## Documentation
10
+ require 'yard'
11
+
12
+ YARD::Rake::YardocTask.new do |task|
13
+ task.files = ['README.md', 'lib/**/*.rb']
14
+ task.options = ['--output-dir', 'doc',
15
+ '--markup', 'markdown',
16
+ '--template-path', './yard',
17
+ '--readme', 'README.md', '-']
18
+ end
19
+
20
+ ## Rspec testing
21
+ require 'ci/reporter/rake/rspec'
22
+ require "rspec/core/rake_task"
23
+
24
+ namespace :spec do
25
+ desc "Run RSpec unit tests"
26
+ RSpec::Core::RakeTask.new(:unit) do |t|
27
+ t.pattern = Dir['spec/**/*_spec.rb'].reject{ |f| f['/integration'] }
28
+ end
29
+
30
+ desc "Run RSpec integration tests"
31
+ RSpec::Core::RakeTask.new(:integration) do |t|
32
+ t.pattern = "spec/integration/**/*_spec.rb"
33
+ end
34
+
35
+ desc "Run all RSpec tests"
36
+ RSpec::Core::RakeTask.new(:all) do |t|
37
+ t.pattern = Dir['spec/**/*_spec.rb']
38
+ end
39
+ end
40
+
41
+ ## Debug console
42
+ desc 'Run pry with gini-api already loaded'
43
+ task :console do
44
+ require 'pry'
45
+ require 'gini-api'
46
+ ARGV.clear
47
+ Pry.start
48
+ end
data/gini-api.gemspec ADDED
@@ -0,0 +1,45 @@
1
+ # coding: utf-8
2
+ lib = File.expand_path('../lib', __FILE__)
3
+ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
4
+
5
+ require 'gini-api/version'
6
+
7
+ gem_version = Gini::Api::BASE_VERSION.dup
8
+
9
+ if ENV.has_key?('BUILD_NUMBER')
10
+ gem_version << ".#{ENV['BUILD_NUMBER']}"
11
+ else
12
+ gem_version = Gini::Api::VERSION
13
+ end
14
+
15
+ Gem::Specification.new do |spec|
16
+ spec.name = 'gini-api'
17
+ spec.version = gem_version
18
+ spec.authors = ['Daniel Kerwin']
19
+ spec.email = ['tech@gini.net']
20
+ spec.description = %q{Ruby client to interact with the Gini API.}
21
+ spec.summary = spec.description
22
+ spec.homepage = 'https://www.gini.net'
23
+ spec.license = 'MIT'
24
+
25
+ spec.files = `git ls-files`.split($/)
26
+ spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
27
+ spec.require_paths = ['lib']
28
+
29
+ spec.add_runtime_dependency 'oauth2'
30
+ spec.add_runtime_dependency 'logger'
31
+ spec.add_runtime_dependency 'eventmachine'
32
+
33
+ spec.add_development_dependency 'pry'
34
+ spec.add_development_dependency 'rake'
35
+ spec.add_development_dependency 'rspec'
36
+ spec.add_development_dependency 'redcarpet'
37
+ spec.add_development_dependency 'yard'
38
+ spec.add_development_dependency 'bundler'
39
+ spec.add_development_dependency 'guard-rspec'
40
+ spec.add_development_dependency 'simplecov'
41
+ spec.add_development_dependency 'simplecov-rcov'
42
+ spec.add_development_dependency 'ci_reporter'
43
+ spec.add_development_dependency 'webmock'
44
+ spec.add_development_dependency 'coveralls'
45
+ end