gini-api 0.9.2
Sign up to get free protection for your applications and to get access to all the features.
- 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
|
+
[![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
|