rightsignature 0.1.8 → 1.0.0

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.
data/README.md CHANGED
@@ -8,21 +8,21 @@ gem install rightsignature
8
8
  ```
9
9
  or in your Gemfile
10
10
  ```
11
- gem 'rightsignature', '~> 0.1.8'
11
+ gem 'rightsignature', '~> 1.0.0'
12
12
  ```
13
13
 
14
14
  Setup
15
15
  -----
16
- After getting an API key from RightSignature, you can use the Secure Token or generate an Access Token with the OAuth key and secret using RightSignature::load_configuration. Below are examples on how to use the gem as yourself.
16
+ After getting an API key from RightSignature, you can use the Secure Token or generate an Access Token with the OAuth key and secret using RightSignature::Connection.new. Below are examples on how to use the gem as yourself.
17
17
 
18
18
  #####Using Token authentication
19
19
  ```
20
- RightSignature::load_configuration(:api_token => YOUR_TOKEN)
20
+ @rs_connection = RightSignature::Connection.new(:api_token => YOUR_TOKEN)
21
21
  ```
22
22
 
23
23
  #####Using OAuth authentication
24
24
  ```
25
- RightSignature::load_configuration(
25
+ @rs_connection = RightSignature::Connection.new(
26
26
  :consumer_key => "Consumer123",
27
27
  :consumer_secret => "Secret098",
28
28
  :access_token => "AccessToken098",
@@ -34,42 +34,42 @@ Note: if the both OAuth credentials and api_token are set, the default action is
34
34
  #####Getting Access Token
35
35
  Make sure you have a server that is can recieve the parameters from RightSignature and the callback is setup correctly in the RightSignature API settings (https://rightsignature.com/oauth_clients).
36
36
  ```
37
- request_token = RightSignature::OauthConnection.new_request_token
37
+ request_token = @rs_connection.new_request_token
38
38
  ```
39
39
 
40
40
  Now Visit the url generated from
41
41
  ```
42
- RightSignature::OauthConnection.request_token.authorize_url
42
+ @rs_oauth = RightSignature::OauthConnection.new(@rs_connection)
43
+ @rs_oauth.request_token.authorize_url
43
44
  ```
44
45
  and log into the site.
45
46
 
46
47
  After approving the application, you will be redirected to the callback url that is in the RightSignature API settings (https://rightsignature.com/oauth_clients). The OAuth verifier should be in the params "oauth_verifier". Put the verifier in:
47
48
  ```
48
- RightSignature::OauthConnection.generate_access_token(params[:oauth_verifer])
49
+ @rs_oauth = RightSignature::OauthConnection.new(@rs_connection)
50
+ @rs_oauth.generate_access_token(params[:oauth_verifer])
49
51
  ```
50
52
 
51
53
  Now, you should have your Connection setup. You can save the access token and access token secret for later use and skip the previous steps.
52
54
  ```
53
- RightSignature::OauthConnection.access_token.token
54
- RightSignature::OauthConnection.access_token.secret
55
+ @rs_oauth.access_token.token
56
+ @rs_oauth.access_token.secret
55
57
  ```
56
58
  Will give you the Access Token's token and secret.
57
59
 
58
60
  You can also load the Access Token and Secret by calling
59
61
  ```
60
- RightSignature::OauthConnection.set_access_token(token, secret)
62
+ @rs_oauth.set_access_token(token, secret)
61
63
  ```
62
64
 
63
- After loading the configuration, you can use wrappers in RightSignature::Document, RightSignature::Template, or RightSignature::Account to call the API. Or use RightSignature::Connection for a more custom call.
65
+ After loading the configuration, you can use wrappers in RightSignature::Connection to call the API, or use RightSignature::Connection for more custom calls.
64
66
 
65
67
  Documents
66
68
  ---------
67
- API calls involving documents are wrapped in the RightSignature::Document class.
68
-
69
69
  #####Listing Document
70
70
  For showing all documents
71
71
  ```
72
- RightSignature::Document.list
72
+ @rs_connection.documents_list
73
73
  ```
74
74
 
75
75
  For showing page 1 of completed and trashed documents, with 20 per page, matching search term 'me', with tag "single_tag" and tag "key" with value of "with_value"
@@ -81,7 +81,7 @@ options = {
81
81
  :search => "me",
82
82
  :tags => ["single_tag", "key" => "with_value"]
83
83
  }
84
- RightSignature::Document.list(options)
84
+ @rs_connection.documents_list(options)
85
85
  ```
86
86
  Optional Options:
87
87
  * page: page number
@@ -102,34 +102,34 @@ Optional Options:
102
102
 
103
103
  #####Document Details
104
104
  ```
105
- RightSignature::Document.details(guid)
105
+ @rs_connection.document_details(guid)
106
106
  ```
107
107
 
108
108
  #####Document Details for Multiple documents
109
109
  ```
110
- RightSignature::Document.batch_details(guids)
110
+ @rs_connection.documents_batch_details(guids)
111
111
  ```
112
112
  * guids: Array of document GUIDs
113
113
 
114
114
  #####Send Reminder
115
115
  ```
116
- RightSignature::Document.resend_reminder(guid)
116
+ @rs_connection.send_reminder(guid)
117
117
  ```
118
118
 
119
119
  #####Trash Document
120
120
  ```
121
- RightSignature::Document.trash(guid)
121
+ @rs_connection.trash_document(guid)
122
122
  ```
123
123
 
124
124
  #####Extend Expiration of Document by 7 days
125
125
  ```
126
- RightSignature::Document.extend_expiration(guid)
126
+ @rs_connection.extend_expiration(guid)
127
127
  ```
128
128
 
129
129
  #####Replace Tags on Document
130
130
  ```
131
131
  tags=['sent_from_api', {'user_id' => '12345'}]
132
- RightSignature::Document.update_tags(guid, tags)
132
+ @rs_connection.update_document_tags(guid, tags)
133
133
  ```
134
134
  * guid
135
135
  * tags: An array of 'tag_name' or {'tag_name' => 'tag_value'}
@@ -150,11 +150,11 @@ options={
150
150
  'use_text_tags' => false
151
151
  }
152
152
 
153
- RightSignature::Document.send_document_from_file("here/is/myfile.pdf", 'My Subject', recipients, options)
153
+ @rs_connection.send_document_from_file("here/is/myfile.pdf", 'My Subject', recipients, options)
154
154
  ```
155
155
  Or
156
156
  ```
157
- RightSignature::Document.send_document_from_file(File.open("here/is/myfile.pdf", 'r'), 'My Subject', recipients)
157
+ @rs_connection.send_document_from_file(File.open("here/is/myfile.pdf", 'r'), 'My Subject', recipients)
158
158
  ```
159
159
  * subject: Document subject
160
160
  * recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer').
@@ -179,14 +179,14 @@ recipients = [
179
179
  ]
180
180
  raw_data = File.read("here/is/myfile.pdf")
181
181
  filename = "Desired Filename.pdf"
182
- RightSignature::Document.send_document_from_file(raw_data, filename, 'My Subject', recipients)
182
+ @rs_connection.send_document_from_file(raw_data, filename, 'My Subject', recipients)
183
183
  ```
184
184
 
185
185
  #####Embedded Signing Links
186
186
  Generates URLs for the embedded signing page for documents with recipients with email of 'noemail@rightsignature.com'.
187
187
  Returns an array of {:name => "John Bellingham", "url" => "https://rightsignature.com/signatures/embedded?rt=1234"}
188
188
  ```
189
- RightSignature::Document.get_signer_links_for(guid, redirect_location=nil)
189
+ @rs_connection.get_document_signer_links_for(guid, redirect_location=nil)
190
190
  ```
191
191
  Optional Option:
192
192
  * redirect_location: URL to redirect user after signing.
@@ -194,11 +194,9 @@ Optional Option:
194
194
 
195
195
  Templates
196
196
  ---------
197
- API calls involving documents are wrapped in the RightSignature::Template class.
198
-
199
197
  #####Listing Templates
200
198
  ```
201
- RightSignature::Template.list(options={})
199
+ @rs_connection.templates_list(options={})
202
200
  ```
203
201
  Optional Options:
204
202
  * page: page number
@@ -210,13 +208,13 @@ Optional Options:
210
208
 
211
209
  #####Template Details
212
210
  ```
213
- RightSignature::Template.details(guid)
211
+ @rs_connection.template_details(guid)
214
212
  ```
215
213
 
216
214
  #####Prepackage and Send template
217
215
  Most common use of API, clones a template and sends it for signature.
218
216
  ```
219
- RightSignature::Template.prepackage_and_send(guid, roles, options={})
217
+ @rs_connection.prepackage_and_send(guid, roles, options={})
220
218
  ```
221
219
  * guid: template guid to use. Should be a template that was prepackaged
222
220
  * roles: recipient names in array of {:name => "Person's Name", :email => "Email"} hashed by Role ID. Ex. {"signer_A" => {:name => "Your Name", :name => "a@example.com"}}
@@ -235,13 +233,13 @@ Optional options:
235
233
  #####Template Prepacking
236
234
  For cloning a Template before sending it.
237
235
  ```
238
- RightSignature::Template.prepackage(guid)
236
+ @rs_connection.prepackage(guid)
239
237
  ```
240
238
 
241
239
  #####Template Prefilling
242
240
  After prepacking, the new template can be updated with prefill data. This won't send out the template as a document.
243
241
  ```
244
- RightSignature::Template.prefill(guid, subject, roles)
242
+ @rs_connection.prefill(guid, subject, roles)
245
243
  ```
246
244
  * guid: template guid to use. Should be a template that was prepackaged
247
245
  * subject: document subject.
@@ -271,14 +269,14 @@ options = {
271
269
  ],
272
270
  :callback_url => "http://yoursite/callback"
273
271
  }
274
- RightSignature::Template.prefill(guid, subject, roles, options)
272
+ @rs_connection.prefill(guid, subject, roles, options)
275
273
  ```
276
274
 
277
275
 
278
276
  #####Template Sending
279
277
  Send template as a document for signing. Same options as prefill.
280
278
  ```
281
- RightSignature::Template.send_template(guid, subject, roles)
279
+ @rs_connection.send_template(guid, subject, roles)
282
280
  ```
283
281
  * guid: template guid to use. Should be a template that was prepackaged
284
282
  * subject: document subject.
@@ -308,14 +306,14 @@ options = {
308
306
  ],
309
307
  :callback_url => "http://yoursite/callback"
310
308
  }
311
- RightSignature::Template.send_template(guid, subject, roles, options)
309
+ @rs_connection.send_template(guid, subject, roles, options)
312
310
  ```
313
311
 
314
312
  #####Embedded Signing Links for Sent Template
315
313
  Prepackages a template, and sends it out with each recipients marked as a embedded signer (email as noemail@rightsignature.com), then generates embedded signing URLs.
316
314
  Returns an array of {:name => "John Bellingham", "url" => "https://rightsignature.com/signatures/embedded?rt=1234"}
317
315
  ```
318
- RightSignature::Template.send_as_embedded_signers(guid, recipients, options={})
316
+ @rs_connection.send_as_embedded_signers(guid, recipients, options={})
319
317
  ```
320
318
  * guid: guid of template to create document with
321
319
  * recipient: recipient names in array of {:name => "Person's Name"} hashed by Role ID. Ex. {"signer_A" => {:name => "Your Name"}}
@@ -335,7 +333,7 @@ RightSignature::Template.send_as_embedded_signers(guid, recipients, options={})
335
333
  #####Create New Template Link
336
334
  Generate a url that let's someone upload and create a template under OAuth user's account.
337
335
  ```
338
- RightSignature::Template.generate_build_url
336
+ @rs_connection.generate_build_url
339
337
  ```
340
338
 
341
339
  You can also add restrictions to what the person can do:
@@ -365,7 +363,7 @@ options = {
365
363
  :callback_location => "http://example.com/done_signing",
366
364
  :redirect_location => "http://example.com/come_back_here"
367
365
  }
368
- RightSignature::Template.generate_build_url(options)
366
+ @rs_connection.generate_build_url(options)
369
367
  ```
370
368
 
371
369
 
@@ -375,18 +373,18 @@ API calls involving API user's account.
375
373
 
376
374
  #####User Details
377
375
  ```
378
- RightSignature::Account.user_details
376
+ @rs_connection.user_details
379
377
  ```
380
378
 
381
379
  #####Add User to Account
382
380
  ```
383
- RightSignature::Account.add_user(name, email)
381
+ @rs_connection.add_user(name, email)
384
382
  ```
385
383
 
386
384
  #####Usage Report
387
385
  Returns number of documents sent. Can scope to week, month, or day and count only signed, unsigned, or all documents.
388
386
  ```
389
- RightSignature::Account.usage_report(since=nil, signed=nil)
387
+ @rs_connection.usage_report(since=nil, signed=nil)
390
388
  ```
391
389
  * since: Only count documents sent withing the 'week', 'month', or 'day'.
392
390
  * signed: Only count signed documents if 'true', else all documents
@@ -397,7 +395,7 @@ Custom API calls using RightSignature::Connection
397
395
  In case there are new API paths, RightSignature::Connection allows a specific path to be specified.
398
396
  #####Ex. GET https://rightsignature.com/api/documents.xml
399
397
  ```
400
- RightSignature::Connection.get('/api/documents.xml', {:my => 'params'}, {'custom_header' => 'headerValue'})
398
+ @rs_connection.get('/api/documents.xml', {:my => 'params'}, {'custom_header' => 'headerValue'})
401
399
  ```
402
400
 
403
401
  #####Ex. POST https://rightsignature.com/api/documents.xml
@@ -408,14 +406,14 @@ request_hash= {
408
406
  'document_data' => {:type => 'url', :value => 'http://localhost:3000/sub.pdf' }
409
407
  }
410
408
  }
411
- RightSignature::Connection.post('/api/documents.xml', request_hash, {'custom_header' => 'headerValue'})
409
+ @rs_connection.post('/api/documents.xml', request_hash, {'custom_header' => 'headerValue'})
412
410
  ```
413
411
 
414
412
  Development Notes
415
413
  -----------------
416
414
  To load in irb from project root:
417
415
  ```
418
- $:.push File.expand_path("../lib", __FILE__); require "rightsignature"; RightSignature::load_configuration(MY_KEYS)
416
+ $:.push File.expand_path("../lib", __FILE__); require "rightsignature"; RightSignature::Connection.new(MY_KEYS)
419
417
  ```
420
418
 
421
419
  TODO:
@@ -11,52 +11,3 @@ require 'rightsignature/connection/token_connection'
11
11
  require 'rightsignature/connection'
12
12
 
13
13
  XmlFu::Node.symbol_conversion_algorithm = :none
14
-
15
- module RightSignature
16
- class <<self
17
- attr_accessor :configuration
18
-
19
- def load_configuration(creds={})
20
- @configuration = {}
21
- oauth_keys.each do |key|
22
- @configuration[key] = creds[key].to_s
23
- end
24
-
25
- api_token_keys.each do |key|
26
- @configuration[key] = creds[key].to_s
27
- end
28
-
29
- @configuration
30
- end
31
-
32
- def check_credentials
33
- raise "Please set load_configuration with #{api_token_keys.join(',')} or #{oauth_keys.join(',')}" unless has_api_token? || has_oauth_credentials?
34
- end
35
-
36
- def has_api_token?
37
- return false if @configuration.nil?
38
- api_token_keys.each do |key|
39
- return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
40
- end
41
-
42
- return true
43
- end
44
-
45
- def has_oauth_credentials?
46
- return false if @configuration.nil?
47
- oauth_keys.each do |key|
48
- return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
49
- end
50
-
51
- return true
52
- end
53
-
54
- def oauth_keys
55
- [:consumer_key, :consumer_secret, :access_token, :access_secret].freeze
56
- end
57
-
58
- def api_token_keys
59
- [:api_token].freeze
60
- end
61
- end
62
- end
@@ -1,20 +1,18 @@
1
1
  module RightSignature
2
- class Account
3
- class <<self
4
- def user_details
5
- RightSignature::Connection.get "/api/users/user_details.xml"
6
- end
7
-
8
- def add_user(name, email)
9
- RightSignature::Connection.post "/api/users.xml", {:user => {:name => name, :email => email}}
10
- end
11
-
12
- def usage_report(since=nil, signed=nil)
13
- options = {}
14
- options[:since] = since if since && ["month", "week", "day"].include?(since)
15
- options[:signed] = signed.to_s unless signed.nil?
16
- RightSignature::Connection.get "/api/account/usage_report.xml", options
17
- end
2
+ module Account
3
+ def user_details
4
+ get "/api/users/user_details.xml"
5
+ end
6
+
7
+ def add_user(name, email)
8
+ post "/api/users.xml", {:user => {:name => name, :email => email}}
9
+ end
10
+
11
+ def usage_report(since=nil, signed=nil)
12
+ options = {}
13
+ options[:since] = since if since && ["month", "week", "day"].include?(since)
14
+ options[:signed] = signed.to_s unless signed.nil?
15
+ get "/api/account/usage_report.xml", options
18
16
  end
19
17
  end
20
18
  end
@@ -1,84 +1,136 @@
1
1
  module RightSignature
2
2
  class Connection
3
- class << self
4
- def site
5
- if RightSignature::has_api_token?
6
- RightSignature::TokenConnection.base_uri
7
- else
8
- RightSignature::OauthConnection.oauth_consumer.site
9
- end
3
+ include RightSignature::Document
4
+ include RightSignature::Account
5
+ include RightSignature::Template
6
+
7
+ attr_accessor :configuration
8
+ attr_accessor :oauth_connection
9
+ attr_accessor :token_connection
10
+
11
+ def initialize(creds={})
12
+ @configuration = {}
13
+ RightSignature::Connection.oauth_keys.each do |key|
14
+ @configuration[key] = creds[key].to_s
10
15
  end
11
16
 
12
- def put(url, body={}, headers={})
13
- if RightSignature::has_api_token?
14
- options = {}
15
- options[:headers] = headers
16
- options[:body] = XmlFu.xml(body)
17
-
18
- parse_response(RightSignature::TokenConnection.request(:put, url, options))
19
- else
20
- parse_response(RightSignature::OauthConnection.request(:put, url, XmlFu.xml(body), headers))
21
- end
17
+ RightSignature::Connection.api_token_keys.each do |key|
18
+ @configuration[key] = creds[key].to_s
22
19
  end
23
20
 
24
- def delete(url, headers={})
25
- if RightSignature::has_api_token?
26
- options = {}
27
- options[:headers] = headers
21
+ @token_connection = RightSignature::TokenConnection.new(*RightSignature::Connection.api_token_keys.map{|k| @configuration[k]})
22
+ @oauth_connection = RightSignature::OauthConnection.new(@configuration)
28
23
 
29
- parse_response(RightSignature::TokenConnection.request(:delete, url, options))
30
- else
31
- parse_response(RightSignature::OauthConnection.request(:delete, url, headers))
32
- end
24
+ @configuration
25
+ end
26
+
27
+ def check_credentials
28
+ raise "Please set load_configuration with #{RightSignature::Connection.api_token_keys.join(',')} or #{RightSignature::Connection.oauth_keys.join(',')}" unless has_api_token? || has_oauth_credentials?
29
+ end
30
+
31
+ def has_api_token?
32
+ return false if @configuration.nil?
33
+ RightSignature::Connection.api_token_keys.each do |key|
34
+ return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
33
35
  end
34
36
 
35
- def get(url, params={}, headers={})
36
- RightSignature::check_credentials
37
-
38
- if RightSignature::has_api_token?
39
- options = {}
40
- options[:headers] = headers
41
- options[:query] = params
42
- parse_response(RightSignature::TokenConnection.request(:get, url, options))
43
- else
44
- unless params.empty?
45
- url = "#{url}?#{params.sort.map{|param| URI.escape("#{param[0]}=#{param[1]}")}.join('&')}"
46
- end
47
- parse_response(RightSignature::OauthConnection.request(:get, url, headers))
48
- end
37
+ return true
38
+ end
39
+
40
+ def has_oauth_credentials?
41
+ return false if @configuration.nil?
42
+ RightSignature::Connection.oauth_keys.each do |key|
43
+ return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
44
+ end
45
+
46
+ return true
47
+ end
48
+
49
+ def self.oauth_keys
50
+ [:consumer_key, :consumer_secret, :access_token, :access_secret].freeze
51
+ end
52
+
53
+ def self.api_token_keys
54
+ [:api_token].freeze
55
+ end
56
+
57
+ def site
58
+ if has_api_token?
59
+ RightSignature::TokenConnection.base_uri
60
+ else
61
+ @oauth_connection.oauth_consumer.site
49
62
  end
63
+ end
50
64
 
51
- def post(url, body={}, headers={})
52
- RightSignature::check_credentials
65
+ def put(url, body={}, headers={})
66
+ if has_api_token?
67
+ options = {}
68
+ options[:headers] = headers
69
+ options[:body] = XmlFu.xml(body)
53
70
 
54
- if RightSignature::has_api_token?
55
- options = {}
56
- options[:headers] = headers
57
- options[:body] = XmlFu.xml(body)
58
- parse_response(RightSignature::TokenConnection.request(:post, url, options))
59
- else
60
- parse_response(RightSignature::OauthConnection.request(:post, url, XmlFu.xml(body), headers))
61
- end
71
+ parse_response(@token_connection.request(:put, url, options))
72
+ else
73
+ parse_response(@oauth_connection.request(:put, url, XmlFu.xml(body), headers))
62
74
  end
75
+ end
76
+
77
+ def delete(url, headers={})
78
+ if has_api_token?
79
+ options = {}
80
+ options[:headers] = headers
81
+
82
+ parse_response(@token_connection.request(:delete, url, options))
83
+ else
84
+ parse_response(@oauth_connection.request(:delete, url, headers))
85
+ end
86
+ end
87
+
88
+ def get(url, params={}, headers={})
89
+ check_credentials
63
90
 
64
- def parse_response(response)
65
- if response.is_a? Net::HTTPResponse
66
- unless response.is_a? Net::HTTPSuccess
67
- puts response.body
68
- raise RightSignature::ResponseError.new(response)
69
- end
70
-
71
- MultiXml.parse(response.body)
72
- else
73
- unless response.success?
74
- puts response.body
75
- raise RightSignature::ResponseError.new(response)
76
- end
77
-
78
- response.parsed_response
91
+ if has_api_token?
92
+ options = {}
93
+ options[:headers] = headers
94
+ options[:query] = params
95
+ parse_response(@token_connection.request(:get, url, options))
96
+ else
97
+ unless params.empty?
98
+ url = "#{url}?#{params.sort.map{|param| URI.escape("#{param[0]}=#{param[1]}")}.join('&')}"
79
99
  end
100
+ parse_response(@oauth_connection.request(:get, url, headers))
80
101
  end
102
+ end
103
+
104
+ def post(url, body={}, headers={})
105
+ check_credentials
81
106
 
107
+ if has_api_token?
108
+ options = {}
109
+ options[:headers] = headers
110
+ options[:body] = XmlFu.xml(body)
111
+ parse_response(@token_connection.request(:post, url, options))
112
+ else
113
+ parse_response(@oauth_connection.request(:post, url, XmlFu.xml(body), headers))
114
+ end
115
+ end
116
+
117
+ def parse_response(response)
118
+ if response.is_a? Net::HTTPResponse
119
+ unless response.is_a? Net::HTTPSuccess
120
+ puts response.body
121
+ raise RightSignature::ResponseError.new(response)
122
+ end
123
+
124
+ MultiXml.parse(response.body)
125
+ else
126
+ unless response.success?
127
+ puts response.body
128
+ raise RightSignature::ResponseError.new(response)
129
+ end
130
+
131
+ response.parsed_response
132
+ end
82
133
  end
134
+
83
135
  end
84
136
  end