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 +7 -0
- data/.gitignore +7 -0
- data/.rspec +2 -0
- data/.travis.yml +5 -0
- data/Gemfile +3 -0
- data/Guardfile +4 -0
- data/README.md +298 -0
- data/Rakefile +48 -0
- data/gini-api.gemspec +45 -0
- data/lib/gini-api/client.rb +284 -0
- data/lib/gini-api/document/extractions.rb +59 -0
- data/lib/gini-api/document/layout.rb +50 -0
- data/lib/gini-api/document.rb +136 -0
- data/lib/gini-api/documentset.rb +35 -0
- data/lib/gini-api/error.rb +100 -0
- data/lib/gini-api/oauth.rb +175 -0
- data/lib/gini-api/version.rb +9 -0
- data/lib/gini-api.rb +15 -0
- data/spec/gini-api/client_spec.rb +505 -0
- data/spec/gini-api/document/extraction_spec.rb +121 -0
- data/spec/gini-api/document/layout_spec.rb +78 -0
- data/spec/gini-api/document_spec.rb +289 -0
- data/spec/gini-api/documentset_spec.rb +43 -0
- data/spec/gini-api/error_spec.rb +155 -0
- data/spec/gini-api/oauth_spec.rb +412 -0
- data/spec/integration/api_spec.rb +124 -0
- data/spec/integration/files/test.pdf +1860 -0
- data/spec/spec_helper.rb +35 -0
- data/yard/default/fulldoc/html/css/common.css +7 -0
- metadata +293 -0
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
data/.rspec
ADDED
data/.travis.yml
ADDED
data/Gemfile
ADDED
data/Guardfile
ADDED
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
|
+
[](https://travis-ci.org/gini/gini-api-ruby)
|
6
|
+
[](https://codeclimate.com/github/gini/gini-api-ruby)
|
7
|
+
[](https://coveralls.io/r/gini/gini-api-ruby)
|
8
|
+
[](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
|