echosign 1.0.2 → 1.5.0

data/lib/echosign/mega_sign/request.rb

@@ -1,5 +1,4 @@
 module Echosign::Request
-
   # Performs REST create_mega_sign operation
   #
   # @param body [Hash] Request body  (REQUIRED)
@@ -7,13 +6,13 @@ module Echosign::Request
   # @param user_id [String] Echosign user ID  (REQUIRED)
   # @param user_email [String] Echosign user email
   # @return [Hash] MegaSign response body
-  def self.create_mega_sign(body, token, user_id=nil, user_email=nil)
+  def self.create_mega_sign(token, base_uri, body, user_id = nil, user_email = nil)
     headers = { 'Access-Token' => token }
-    headers.merge!('X-User-Id' => user_id) unless user_id.nil?
-    headers.merge!('X-User-Email' => user_email) unless user_email.nil?
-    headers.merge!('Content-Type' => "application/json")
-    response = HTTParty.post(ENDPOINT.fetch(:mega_sign), :body => body.to_json,
-    :headers => headers)
+    headers['X-User-Id'] = user_id unless user_id.nil?
+    headers['X-User-Email'] = user_email unless user_email.nil?
+    headers['Content-Type'] = "application/json"
+    response = HTTParty.post(ENDPOINT.fetch(:megaSign, base_uri), body: body.to_json,
+                                                                  headers: headers)
     JSON.parse(response.body)
   end
 
@@ -21,9 +20,9 @@ module Echosign::Request
   #
   # @param token [String] Auth Token
   # @return [Hash] MegaSigns response body
-  def self.get_mega_signs(token)
+  def self.get_mega_signs(token, base_uri)
     headers = { 'Access-Token' => token }
-    response = get(ENDPOINT.fetch(:mega_sign), headers)
+    response = get(ENDPOINT.fetch(:megaSign, base_uri), headers)
     JSON.parse(response.body)
   end
 
@@ -32,9 +31,9 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
   # @return [Hash] MegaSign info response body
-  def self.mega_sign_info(token, mega_sign_id)
+  def self.mega_sign_info(token, base_uri, mega_sign_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}"
     response = get(endpoint, headers)
     JSON.parse(response.body)
   end
@@ -44,21 +43,22 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
   # @return [Hash] URL information for the eSign page of the mega_sign
-  def self.mega_sign_signing_urls(token, mega_sign_id)
+  def self.mega_sign_signing_urls(token, base_uri, mega_sign_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/signingUrls"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/signingUrls"
     response = get(endpoint, headers)
     JSON.parse(response.body)
   end
 
   # Gets a single combined PDF document for the documents associated with an mega_sign.
-  # 
+  #
   # @param token [String] Auth Token
   # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
   # @return [String] Raw bytes from document file
-  def self.mega_sign_combined_pdf(token, mega_sign_id, versionId, participantEmail, attachSupportingDocuments, auditReport)
+  def self.mega_sign_combined_pdf(token, base_uri, mega_sign_id, versionId, participantEmail,
+                                  attachSupportingDocuments, auditReport)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/combinedDocument"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/combinedDocument"
     endpoint << add_query(endpoint, "versionId=#{versionId}") unless versionId.nil?
     endpoint << add_query(endpoint, "participantEmail=#{participantEmail}") unless participantEmail.nil?
     endpoint << add_query(endpoint, "attachSupportingDocuments=#{attachSupportingDocuments}")
@@ -67,13 +67,13 @@ module Echosign::Request
   end
 
   # Retrieves data entered by the user into interactive form fields at the time they signed the mega_sign
-  # 
+  #
   # @param token [String] Auth Token
   # @param mega_sign_id [String]  (REQUIRED)
   # @return [String] Raw bytes representing CSV file
-  def self.mega_sign_form_data(token, mega_sign_id)
+  def self.mega_sign_form_data(token, base_uri, mega_sign_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/formData"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/formData"
     response = get(endpoint, headers)
   end
 
@@ -82,9 +82,9 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
   # @return [String] Raw bytes from document file
-  def self.mega_sign_document_file(token, mega_sign_id, document_id)
+  def self.mega_sign_document_file(token, base_uri, mega_sign_id, document_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/documents/#{document_id}"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/documents/#{document_id}"
     response = get(endpoint, headers)
   end
 
@@ -93,9 +93,9 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
   # @return [String] Raw bytes from audit pdf file
-  def self.audit_trail_pdf(token, mega_sign_id)
+  def self.audit_trail_pdf(token, base_uri, mega_sign_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/auditTrail"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/auditTrail"
     response = get(endpoint, headers)
   end
 
@@ -103,12 +103,14 @@ module Echosign::Request
   #
   # @param mega_sign_id [String] (REQUIRED)
   # @param recipient_email [String] The email address of the participant to be used to retrieve documents. (REQUIRED)
-  # @param format [String] Content format of the supported documents. It can have two possible values ORIGINAL or CONVERTED_PDF. (REQUIRED)
-  # @param version_id [String] Version of the mega_sign as provided by {mega_sign_info mega_sign_info}.  If not provided, the latest version of the mega_sign is used.
+  # @param format [String] Content format of the supported documents. It can have two possible values ORIGINAL or
+  #   CONVERTED_PDF. (REQUIRED)
+  # @param version_id [String] Version of the mega_sign as provided by {mega_sign_info mega_sign_info}.  If not
+  #   provided, the latest version of the mega_sign is used.
   # @return [Hash] MegaSign documents response body
-  def self.mega_sign_documents(token, mega_sign_id, recipient_email=nil, format=nil, version_id=nil)
+  def self.mega_sign_documents(token, base_uri, mega_sign_id, recipient_email = nil, format = nil, version_id = nil)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/documents"
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/documents"
     endpoint << add_query(endpoint, "versionId=#{version_id}") unless version_id.nil?
     endpoint << add_query(endpoint, "participantEmail=#{recipient_email}") unless version_id.nil?
     endpoint << add_query(endpoint, "supportingDocumentContentFormat=#{format}") unless format.nil?
@@ -116,29 +118,16 @@ module Echosign::Request
     JSON.parse(response.body)
   end
 
-
   # Performs REST PUT /mega_sign/:id operation
   #
   # @param token [String] Auth Token
   # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
   # @param request_body [Hash] Hash for MegaSign status update
   # @return [Hash] MegaSigns response body
-  def self.update_mega_sign_status(token, mega_sign_id, request_body)
+  def self.update_mega_sign_status(token, base_uri, mega_sign_id, request_body)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/status"
-
-    begin
-      response = HTTParty.put(
-        endpoint, 
-        request_body.to_json,
-        headers
-      )
-    rescue Exception => error
-      raise_error(error)
-    end
-
+    endpoint = "#{ENDPOINT.fetch(:megaSign, base_uri)}/#{mega_sign_id}/status"
+    response = put(endpoint, request_body.to_json, headers)
     JSON.parse(response.body)
   end
-
-
 end

data/lib/echosign/refresh.rb

@@ -1,6 +1,5 @@
 module Echosign
   class Refresh < Hash
-
     include Validatable
 
     # Builds a Credentials object
@@ -9,17 +8,14 @@ module Echosign
     # @param client_secret [String] Application secret
     # @param refresh_token [String] OAuth Refresh Token
     def initialize(client_id, client_secret, refresh_token)
-
       merge!(
-      {
-        :client_id => client_id,
-        :client_secret => client_secret,
-        :refresh_token => refresh_token,
-        :grant_type => "refresh_token"
-      }
+        {
+          client_id: client_id,
+          client_secret: client_secret,
+          refresh_token: refresh_token,
+          grant_type: "refresh_token"
+        }
       )
     end
-
   end
 end
-

data/lib/echosign/reminder.rb

@@ -1,13 +1,13 @@
 module Echosign
   class Reminder < Hash
-
     include Validatable
 
     # Reminder options
     #
     # @param [Hash] params SYMBOL-referenced Hash containing exactly one of the following:
     # @option params [String] :agreementId (REQUIRED)
-    # @option params [String] :comment An Optional message sent to the recipients, describing what is being sent and why their signatures are required.
+    # @option params [String] :comment An Optional message sent to the recipients, describing what is being sent and
+    #   why their signatures are required.
     # @return [Echosign::Reminder]
     def initialize(params)
       require_keys([:agreementId], params)

data/lib/echosign/request.rb

@@ -13,42 +13,44 @@ module Echosign::Request
     end
   end
 
-  BASE_URL = 'https://api.eu1.echosign.com/api/rest/v5'
-  REFRESH_URL = 'https://api.eu1.echosign.com/oauth/refresh'
-
-  ENDPOINT = { 
-    token: BASE_URL + '/auth/tokens',
-    refresh: REFRESH_URL,
-    user: BASE_URL + '/users',
-    agreement: BASE_URL + '/agreements',
-    mega_sign: BASE_URL + '/megaSigns',
-    reminder: BASE_URL + '/reminders',
-    transientDocument: BASE_URL + '/transientDocuments',
-    libraryDocument: BASE_URL + '/libraryDocuments',
-    widget: BASE_URL + '/widgets'
-  }
-
-  # Retrieves the authentication token
-  #
-  # @param credentials [Echosign::Credentials] Initialized Echosign::Credentials
-  # @return [String] Valid authentication token
-  def self.get_token(credentials)
-    headers = {}
-    response = post(ENDPOINT.fetch(:token), credentials, headers)
-    response_body = JSON.parse(response.body)
-    response_body.fetch("access_token")
+  BASE_URL  = 'https://api.echosign.com/'
+  BASE_PATH = 'api/rest/v5'
+
+  class EndpointHash
+    def initialize(paths)
+      @paths = paths
+    end
+
+    # Get an endpoint by name, using the given base_uri
+    #
+    # @param endpoint [Symbol] A legal endpoint name, as a symbol
+    # @param base_uri [String] A URI that was retrieved from the base_uris API
+    # @return [String] Returns a URL for the endpoint that begins with the base_uri
+    def fetch(endpoint, base_uri)
+      File.join(base_uri, BASE_PATH, @paths.fetch(endpoint))
+    end
   end
 
-  # Retrieves the authentication token
-  #
-  # @param credentials [Echosign::Credentials] Initialized Echosign::Credentials
-  # @return [String] Valid authentication token
-  def self.get_token_from_refresh(credentials)
-    # headers = { :content_type => "application/x-www-form-urlencoded" }
-    headers = {}
-    response = post(ENDPOINT.fetch(:refresh), credentials, headers)
-    response_body = JSON.parse(response.body)
-    response_body.fetch("access_token")
+  ENDPOINT = EndpointHash.new({
+                                base_uri: '/base_uris',
+                                transientDocument: '/transientDocuments',
+                                agreement: '/agreements',
+                                reminder: '/reminders',
+                                user: '/users',
+                                libraryDocument: '/libraryDocuments',
+                                widget: '/widgets',
+                                view: '/views',
+                                search: '/search',
+                                workflow: '/workflows',
+                                group: '/groups',
+                                megaSign: '/megaSigns',
+                              }).freeze
+
+  def self.get_base_uris(token)
+    endpoint = ENDPOINT.fetch(:base_uri, BASE_URL)
+    headers = { 'Access-Token' => token }
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
   end
 
   # Performs REST create_user operation
@@ -56,23 +58,23 @@ module Echosign::Request
   # @param body [Hash] Valid request body
   # @param token [String] Auth Token
   # @return [Hash] New user response body
-  def self.create_user(body, token)
-    endpoint = ENDPOINT.fetch(:user) 
-    headers = { 'Access-Token' => token}
+  def self.create_user(token, base_uri, body)
+    endpoint = ENDPOINT.fetch(:user, base_uri)
+    headers = { 'Access-Token' => token }
     response = post(endpoint, body, headers)
     JSON.parse(response.body)
   end
-  
+
   # Sends a reminder for an agreement.
   #
   # @param body [Hash] Valid request body
   # @param token [String] Auth Token
   # @return [Hash] Response body
-  def self.create_reminder(token, body)
-  endpoint = ENDPOINT.fetch(:reminder)
-  headers = { 'Access-Token' => token}
-  response = post(endpoint, body, headers)
-  JSON.parse(response.body)
+  def self.create_reminder(token, base_uri, body)
+    endpoint = ENDPOINT.fetch(:reminder, base_uri)
+    headers = { 'Access-Token' => token }
+    response = post(endpoint, body, headers)
+    JSON.parse(response.body)
   end
 
   # Performs REST create_transient_document operation
@@ -82,70 +84,79 @@ module Echosign::Request
   # @param file_handle [File] File handle (REQUIRED)
   # @param mime_type [String] Mime type
   # @return [Hash] Transient Document Response Body
-  def self.create_transient_document(token, file_name, file_handle, mime_type=nil)
+  def self.create_transient_document(token, base_uri, file_name, file_handle, mime_type = nil)
     headers = { 'Access-Token' => token }
+    if file_handle.is_a?(String)
+      raise "Cannot find file: #{file_handle}" unless File.exist?(file_handle)
 
-    begin
-      response = HTTParty.post( 
-                                 ENDPOINT.fetch(:transientDocument), 
-                                 { 'File-Name' => file_name, 
-                                   'Mime-Type' => mime_type, 
-                                   'File' => file_handle,  
-                                   :multipart => true}, 
-                                   headers
-                                )
-    rescue Exception => error
-      raise_error(error)
+      file_handle = File.new(file_handle)
     end
+    body = { 'File-Name' => file_name, 'Mime-Type' => mime_type, 'File' => file_handle }
+    response = post(ENDPOINT.fetch(:transientDocument, base_uri), body, headers)
 
     JSON.parse(response.body)
   end
 
-  # Gets all the users in an account that the caller has permissions to access. 
+  # Gets all the users in an account that the caller has permissions to access.
   #
   # @param token [String] Auth Token
   # @param user_email [String] The email address of the user whose details are being requested.
   # @return [Hash] User info hash
-  def self.get_users(token, user_email)
+  def self.get_users(token, base_uri, user_email)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:user)}?x-user-email=#{user_email}"
+    endpoint = "#{ENDPOINT.fetch(:user, base_uri)}?x-user-email=#{user_email}"
     response = get(endpoint, headers)
-    JSON.parse(response)
+    JSON.parse(response.body)
   end
 
-  # Gets all the users in an account that the caller has permissions to access. 
+  # Gets all the users in an account that the caller has permissions to access.
   #
   # @param token [String] Auth Token
   # @param user_id [String]
   # @return [Hash] User info hash
-  def self.get_user(token, user_id)
+  def self.get_user(token, base_uri, user_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:user)}/#{user_id}"
+    endpoint = "#{ENDPOINT.fetch(:user, base_uri)}/#{user_id}"
     response = get(endpoint, headers)
-    JSON.parse(response)
+    JSON.parse(response.body)
   end
 
-
   private
 
   def self.get(endpoint, headers)
+    # puts "[Echosign] #{endpoint}"
     begin
-      HTTParty.get(
-        endpoint, 
+      response = HTTParty.get(
+        endpoint,
         headers: headers
       )
+      response
     rescue Exception => error
       raise_error(error)
     end
   end
 
-  def self.post(endpoint, body, headers)
+  def self.post(endpoint, body, headers, options = {})
+    option = { json: false }.merge(options)
+    # puts "[Echosign] #{endpoint}"
+    # puts "[Echosign] #{body}"
     begin
-      HTTParty.post(
-        endpoint,
-        query: body, 
-        headers: headers
-      )
+      if options[:json]
+        headers['Content-Type'] = 'application/json'
+        body = body.to_json if body.is_a?(Hash)
+      end
+      response = HTTParty.post(endpoint, body: body, headers: headers)
+      response
+    rescue Exception => error
+      raise_error(error)
+    end
+  end
+
+  def self.put(endpoint, query, headers)
+    begin
+      headers['Content-Type'] = 'application/json'
+      response = HTTParty.put(endpoint, body: query, headers: headers)
+      response
     rescue Exception => error
       raise_error(error)
     end
@@ -157,9 +168,8 @@ module Echosign::Request
 
   def self.raise_error(error)
     puts error
-    message = "#{error.inspect}.  \nSee Adobe Echosign REST API documentation for Error code meanings: https://secure.echosign.com/public/docs/restapi/v5"
+    message = "#{error.inspect}.  \nSee Adobe Echosign REST API documentation for Error code meanings: " \
+      "https://secure.echosign.com/public/docs/restapi/v5"
     raise Failure.new message, error
   end
-
 end
-

data/lib/echosign/user.rb

@@ -1,6 +1,5 @@
 module Echosign
   class User < Hash
-
     include Validatable
 
     # Creates a user for the current application
@@ -10,20 +9,27 @@ module Echosign
     # @option params [String] :password The new user's password (REQUIRED)
     # @option params [String] :firstName The first name of the new user (REQUIRED)
     # @option params [String] :lastName The last name of the new user (REQUIRED)
-    # @option params [String] :optIn 'YES' or 'NO' or 'UNKNOWN': Whether or not the user has opted in to recieve marketing information from EchoSign and its partners. Default value is UNKNOWN
-    # @option params [String] :groupId Group in which the new user should be added. It can be obtained through GET /users call. Default is Group of the user making this call. The user is inferred from the access_token header
+    # @option params [String] :optIn 'YES' or 'NO' or 'UNKNOWN': Whether or not the user has opted in to recieve
+    #   marketing information from EchoSign and its partners. Default value is UNKNOWN
+    # @option params [String] :groupId Group in which the new user should be added. It can be obtained through GET
+    #   /users call. Default is Group of the user making this call. The user is inferred from the access_token header
     # @option params [String] :title The new user's job title
     # @option params [String] :phone The phone number of the new user
     # @option params [String] :company The name of the new user's company
-    # @option params [String] :customField1 You can choose to use custom fields to record additional information about your new users. These fields are, however, available only with customized implementations - please contact EchoSign if you would like to make use of this functionality
-    # @option params [String] :customField2 You can choose to use custom fields to record additional information about your new users. These fields are, however, available only with customized implementations - please contact EchoSign if you would like to make use of this functionality
-    # @option params [String] :customField3 You can choose to use custom fields to record additional information about your new users. These fields are, however, available only with customized implementations - please contact EchoSign if you would like to make use of this functionality
+    # @option params [String] :customField1 You can choose to use custom fields to record additional information
+    #   about your new users. These fields are, however, available only with customized implementations - please
+    #   contact EchoSign if you would like to make use of this functionality
+    # @option params [String] :customField2 You can choose to use custom fields to record additional information
+    #   about your new users. These fields are, however, available only with customized implementations - please
+    #   contact EchoSign if you would like to make use of this functionality
+    # @option params [String] :customField3 You can choose to use custom fields to record additional information
+    #   about your new users. These fields are, however, available only with customized implementations - please
+    #   contact EchoSign if you would like to make use of this functionality
     # @return [String] User ID
 
     def initialize(params)
       require_keys([:firstName, :lastName, :email, :password], params)
       merge!(params)
     end
-
   end # class User
 end # module Echosign