echosign 1.0.2 → 1.5.0

data/lib/echosign/agreement/fileinfo.rb

@@ -1,9 +1,8 @@
 module Echosign
   class Fileinfo < Hash
-
     include Validatable
 
-    # Validates Fileinfo params 
+    # Validates Fileinfo params
     #
     # @param [Hash] params SYMBOL-referenced Hash containing exactly one of the following:
     # @option params [String] :transientDocumentId A transient document ID available to the sender
@@ -17,4 +16,3 @@ module Echosign
     end
   end
 end
-

data/lib/echosign/agreement/form_field_location.rb

@@ -1,9 +1,8 @@
 module Echosign
   class FormFieldLocation < Hash
-
     include Validatable
 
-    # Validates FormFieldLocation params 
+    # Validates FormFieldLocation params
     #
     # @param [Hash] params SYMBOL-referenced Hash containing exactly one of the following:
     # @option param [Integer] height (double): Height of the form field in pixels,
@@ -17,4 +16,4 @@ module Echosign
       merge!(params)
     end
   end
-end
+end

data/lib/echosign/agreement/phone_info.rb

@@ -1,19 +1,19 @@
 module Echosign
   class PhoneInfo < Hash
-
     include Validatable
 
-    # PhoneInfo 
+    # PhoneInfo
     #
     # @param [Hash] params SYMBOL-referenced Hash.
-    # @option params [String] :phone The phone number required for the recipient to view and sign the document (REQUIRED)
-    # @option params [String] :countryCode The phoneInfo country code required for the recipient to view and sign the document if authentication type is PHONE
+    # @option params [String] :phone The phone number required for the recipient to view and sign the document
+    #   (REQUIRED)
+    # @option params [String] :countryCode The phoneInfo country code required for the recipient to view and sign
+    #   the document if authentication type is PHONE
     # @return [Echosign::PhoneInfo]
 
     def initialize(params)
       require_keys([:phone], params)
       merge!(params)
     end
-
   end
 end

data/lib/echosign/agreement/recipient.rb

@@ -1,22 +1,23 @@
 module Echosign
   class Recipient < Hash
-
     include Validatable
 
-    # Creates an Echosign::Recipient object 
+    # Creates an Echosign::Recipient object
     #
     # @param [Hash] params SYMBOL-referenced Hash.  Role, and either fax or email is required.
     # @option params [String] :role ['SIGNER' or 'APPROVER']: Specify the role of recipient (REQUIRED)
-    # @option params [String] :email Email of the recipient. This is required if fax is not provided. Both fax and email can not be provided (email or fax REQUIRED)
-    # @option params [String] :fax Fax of the recipient. This is required if email is not provided. Both fax and email can not be provided (email or fax REQUIRED)
-    # @option params [Array] :securityOptions Security options that apply to the recipient.  Populate the array with instances of {Echosign::RecipientSecurityOption Echosign::RecipientSecurityOption}
+    # @option params [String] :email Email of the recipient. This is required if fax is not provided. Both fax and
+    #   email can not be provided (email or fax REQUIRED)
+    # @option params [String] :fax Fax of the recipient. This is required if email is not provided. Both fax and
+    #   email can not be provided (email or fax REQUIRED)
+    # @option params [Array] :securityOptions Security options that apply to the recipient.  Populate the array with
+    #   instances of {Echosign::RecipientSecurityOption Echosign::RecipientSecurityOption}
     # @return [Echosign::Recipient]
 
     def initialize(params)
       require_exactly_one([:email, :fax], params)
-      merge!(params)
+      email_or_fax = params[:email] ? { email: params[:email] } : { fax: params[:fax] }
+      merge!(recipientSetMemberInfos: email_or_fax, recipientSetRole: params[:role])
     end
-
   end
 end
-

data/lib/echosign/agreement/recipient_security_option.rb

@@ -1,13 +1,15 @@
 module Echosign
   class RecipientSecurityOption < Hash
-
     include Validatable
 
     # Validates RecipientSecurityOption parameters
     #
     # @param [Hash] params SYMBOL-referenced Hash.
-    # @option params [String] :authenticationMethod ['INHERITED_FROM_DOCUMENT' or 'KBA' or 'PASSWORD' or 'WEB_IDENTITY' or 'PHONE' or 'NONE']: The authentication method for the recipients to have access to view and sign the document. (REQUIRED)
-    # @option params [Array] :phoneInfos The phoneInfo required for the recipient to view and sign the document.  Populate with instances of {Echosign::PhoneInfo Echosign::PhoneInfo}
+    # @option params [String] :authenticationMethod ['INHERITED_FROM_DOCUMENT' or 'KBA' or 'PASSWORD' or
+    #   'WEB_IDENTITY' or 'PHONE' or 'NONE']: The authentication method for the recipients to have access to view
+    #   and sign the document. (REQUIRED)
+    # @option params [Array] :phoneInfos The phoneInfo required for the recipient to view and sign the document.
+    #   Populate with instances of {Echosign::PhoneInfo Echosign::PhoneInfo}
     # @option params [String] :password The password required for the recipient to view and sign the document.
     # @return [Echosign::RecipientSecurityOption]
 
@@ -15,6 +17,5 @@ module Echosign
       require_keys([:authenticationMethod], params)
       merge! params
     end
-
   end
 end

data/lib/echosign/agreement/request.rb

@@ -1,5 +1,4 @@
 module Echosign::Request
-
   # Performs REST create_agreement operation
   #
   # @param body [Hash] Request body  (REQUIRED)
@@ -7,13 +6,11 @@ module Echosign::Request
   # @param user_id [String] Echosign user ID  (REQUIRED)
   # @param user_email [String] Echosign user email
   # @return [Hash] Agreement response body
-  def self.create_agreement(body, token, user_id=nil, user_email=nil)
+  def self.create_agreement(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(:agreement), :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?
+    response = post(ENDPOINT.fetch(:agreement, base_uri), body, headers, json: true)
     JSON.parse(response.body)
   end
 
@@ -21,9 +18,9 @@ module Echosign::Request
   #
   # @param token [String] Auth Token
   # @return [Hash] Agreements response body
-  def self.get_agreements(token)
+  def self.get_agreements(token, base_uri)
     headers = { 'Access-Token' => token }
-    response = get(ENDPOINT.fetch(:agreement), headers)
+    response = get(ENDPOINT.fetch(:agreement, base_uri), headers)
     JSON.parse(response.body)
   end
 
@@ -32,9 +29,9 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param agreement_id [String] ID of agreement to retrieve info on.
   # @return [Hash] Agreement info response body
-  def self.agreement_info(token, agreement_id)
+  def self.agreement_info(token, base_uri, agreement_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_id}"
     response = get(endpoint, headers)
     JSON.parse(response.body)
   end
@@ -44,36 +41,38 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param agreement_id [String] ID of agreement to retrieve info on.
   # @return [Hash] URL information for the eSign page of the agreement
-  def self.agreement_signing_urls(token, agreement_id)
+  def self.agreement_signing_urls(token, base_uri, agreement_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/signingUrls"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_id}/signingUrls"
     response = get(endpoint, headers)
     JSON.parse(response.body)
   end
 
   # Gets a single combined PDF document for the documents associated with an agreement.
-  # 
+  #
   # @param token [String] Auth Token
   # @param agreement_id [String] ID of agreement to retrieve info on.
   # @return [String] Raw bytes from document file
-  def self.agreement_combined_pdf(token, agreement_id, versionId, participantEmail, attachSupportingDocuments, auditReport)
+  def self.agreement_combined_pdf(token, base_uri, agreement_id, versionId, participantEmail,
+                                  attachSupportingDocuments, auditReport)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/combinedDocument"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_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}")
     endpoint << add_query(endpoint, "auditReport=#{auditReport}")
     response = get(endpoint, headers)
+    response.body
   end
 
   # Retrieves data entered by the user into interactive form fields at the time they signed the agreement
-  # 
+  #
   # @param token [String] Auth Token
   # @param agreement_id [String]  (REQUIRED)
   # @return [String] Raw bytes representing CSV file
-  def self.agreement_form_data(token, agreement_id)
+  def self.agreement_form_data(token, base_uri, agreement_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/formData"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_id}/formData"
     response = get(endpoint, headers)
   end
 
@@ -82,10 +81,11 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param agreement_id [String] ID of agreement to retrieve info on.
   # @return [String] Raw bytes from document file
-  def self.agreement_document_file(token, agreement_id, document_id)
+  def self.agreement_document_file(token, base_uri, agreement_id, document_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/documents/#{document_id}"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_id}/documents/#{document_id}"
     response = get(endpoint, headers)
+    response.body
   end
 
   # Performs REST GET /agreement/:id/auditTrail operation
@@ -93,22 +93,25 @@ module Echosign::Request
   # @param token [String] Auth Token
   # @param agreement_id [String] ID of agreement to retrieve info on.
   # @return [String] Raw bytes from audit pdf file
-  def self.audit_trail_pdf(token, agreement_id)
+  def self.audit_trail_pdf(token, base_uri, agreement_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/auditTrail"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_id}/auditTrail"
     response = get(endpoint, headers)
+    response.body
   end
 
   # Performs REST GET /agreement/:id/documents
   #
   # @param agreement_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 agreement as provided by {agreement_info agreement_info}.  If not provided, the latest version of the agreement 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 agreement as provided by {agreement_info agreement_info}.  If not
+  #   provided, the latest version of the agreement is used.
   # @return [Hash] Agreement documents response body
-  def self.agreement_documents(token, agreement_id, recipient_email=nil, format=nil, version_id=nil)
+  def self.agreement_documents(token, base_uri, agreement_id, recipient_email = nil, format = nil, version_id = nil)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/documents"
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_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 +119,16 @@ module Echosign::Request
     JSON.parse(response.body)
   end
 
-
   # Performs REST PUT /agreement/:id operation
   #
   # @param token [String] Auth Token
   # @param agreement_id [String] ID of agreement to retrieve info on.
   # @param request_body [Hash] Hash for Agreement status update
   # @return [Hash] Agreements response body
-  def self.update_agreement_status(token, agreement_id, request_body)
+  def self.update_agreement_status(token, base_uri, agreement_id, request_body)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/status"
-
-    begin
-      response = HTTParty.put(
-        endpoint, 
-        request_body.to_json,
-        headers
-      )
-    rescue Exception => error
-      raise_error(error)
-    end
-
+    endpoint = "#{ENDPOINT.fetch(:agreement, base_uri)}/#{agreement_id}/status"
+    response = put(endpoint, request_body.to_json, headers)
     JSON.parse(response.body)
   end
-
-
 end

data/lib/echosign/agreement/request_form_field.rb

@@ -1,9 +1,8 @@
 module Echosign
   class RequestFormField < Hash
-
     include Validatable
 
-    # Validates RequestFormField params 
+    # Validates RequestFormField params
     #
     # @param [Hash] params SYMBOL-referenced Hash containing exactly one of the following:
     # @return [Echosign::RequestFormField]
@@ -12,4 +11,4 @@ module Echosign
       merge!(params)
     end
   end
-end
+end

data/lib/echosign/agreement/url_file_info.rb

@@ -1,18 +1,20 @@
 module Echosign
   class UrlFileInfo < Hash
-
     include Validatable
 
     # Validates UrlFileInfo parameters
     #
-    # @param [Hash] params SYMBOL-referenced Hash 
-    # @option params [String] :url A publicly accessible URL for retrieving the raw file content. HTTP authentication is supported using standard embedded syntax - i.e. http://username:password@your.server.com/path/to/file (REQUIRED)
-    # @option params [String] :mimeType The mime type of the referenced file, used to determine if the file can be accepted and the necessary conversion steps can be performed.
-    # @option params [String] :name The original system file name of the document being sent - used to name attachments, and to infer the mime type if one is not explicitly specified
+    # @param [Hash] params SYMBOL-referenced Hash
+    # @option params [String] :url A publicly accessible URL for retrieving the raw file content. HTTP
+    #   authentication is supported using standard embedded syntax - i.e.
+    #   http://username:password@your.server.com/path/to/file (REQUIRED)
+    # @option params [String] :mimeType The mime type of the referenced file, used to determine if the file can be
+    #   accepted and the necessary conversion steps can be performed.
+    # @option params [String] :name The original system file name of the document being sent - used to name
+    #   attachments, and to infer the mime type if one is not explicitly specified
     def initialize(params)
       require_keys([:url], params)
       merge! params
     end
   end
 end
-

data/lib/echosign/client.rb

@@ -2,18 +2,17 @@ require 'echosign/agreement/client'
 require 'echosign/library_documents/client'
 require 'echosign/widget/client'
 
-
 module Echosign
-
-  class Client 
-
+  class Client
     attr_reader :token
+
     # Initializes the Client object
     #
-    # @param credentials [Echosign::Credentials] Initialized Echosign::Credentials
-    # @return [Echosign::Client] Initialized Echosign::Client 
-    def initialize(credentials)
-      @token = Echosign::Request.get_token_from_refresh(credentials)
+    # @param token [String] Access token or integration key
+    # @return [Echochamber::Client] Initialized Echochamber::Client
+    def initialize(token)
+      @token = token
+      @base_uri = nil
     end
 
     # Creates a user for the current application
@@ -21,26 +20,26 @@ module Echosign
     # @param user [Echosign::User]
     # @return [String] User ID of new Echosign user
     def create_user(user)
-      user_response  = Echosign::Request.create_user(user, token)
+      user_response = request(:create_user, user)
       user_response.fetch("userId")
     end
 
-    # Creates a reminder 
+    # Creates a reminder
     #
     # @param reminder [Echosign::Reminder]
     # @return [String] Reminder ID
     def create_reminder(reminder)
-      reminder_response = Echosign::Request.create_reminder(token, reminder)
+      reminder_response = request(:create_reminder, reminder)
     end
 
     # Creates a transient document for later referral
     #
-    # @param file_name [String] 
-    # @param mime_type [String] 
-    # @param file_handle [File] 
+    # @param file_name [String]
+    # @param mime_type [String]
+    # @param file_handle [File]
     # @return [String] Transient document ID
     def create_transient_document(file_name, mime_type, file_handle)
-      transient_document_response = Echosign::Request.create_transient_document(token, file_name, file_handle, mime_type)
+      transient_document_response = request(:create_transient_document, file_name, file_handle, mime_type)
       transient_document_response.fetch("transientDocumentId")
     end
 
@@ -49,8 +48,8 @@ module Echosign
     # @param agreement_id [String]  (REQUIRED)
     # @param file_path [String] File path to save the document.  If no file path is given, nothing is saved to disk.
     # @return [String] Raw bytes from document file
-    def audit_trail_pdf(agreement_id, file_path=nil)
-      response = Echosign::Request.audit_trail_pdf(token, agreement_id)
+    def audit_trail_pdf(agreement_id, file_path = nil)
+      response = request(:audit_trail_pdf, agreement_id)
       unless file_path.nil?
         file = File.new(file_path, 'wb')
         file.write(response)
@@ -59,24 +58,34 @@ module Echosign
       response
     end
 
-
     # Gets all the users in an account that the caller has permissions to access.
-    # 
+    #
     # @param user_email [String] The email address of the user whose details are being requested  (REQUIRED)
     # @return [Hash] User info hash
     def get_users(user_email)
-      Echosign::Request.get_users(token, user_email)
+      request(:get_users, user_email)
     end
 
     # Gets all the users in an account that the caller has permissions to access.
-    # 
+    #
     # @param user_id [String]
     # @return [Hash] User info hash
     def get_user(user_id)
-      Echosign::Request.get_user(token, user_id)
+      request(:get_user, user_id)
     end
 
+    private
 
-  end # class Client 
-
+    # Call an Echosign::Request method with this client's token and base_uri
+    #
+    # @param method [Symbol] The name of the ultimate method to call
+    # @param params Any number of parameters to be passed to the ultimate method
+    # @return Returns the result of the ultimate method
+    #
+    # Note: params will be prepended with token and base_uri before calling the ultimate method
+    def request(method, *params)
+      @base_uri ||= Echosign::Request.get_base_uris(@token).fetch('api_access_point')
+      Echosign::Request.send(method, @token, @base_uri, *params)
+    end
+  end # class Client
 end # module Echosign

data/lib/echosign/credentials.rb

@@ -1,33 +1,104 @@
 module Echosign
-  class Credentials < Hash
+  class Credentials
+    require 'oauth2'
 
     include Validatable
 
-    # Builds a Credentials object
-    #
-    # @param app_id [String] Application key
-    # @param app_secret [String] Application secret
-    # @param api_key [String] API Key
-    # @param email [String] User email 
-    # @param password [String] User password
-    # @return [Echosign::Credentials] Echosign credentials
-    def initialize(app_id, app_secret, api_key, email, password)
-
-      merge!(
-        {
-          applicationCredentials:  {
-          applicationId: app_id,
-          applicationSecret: app_secret
-        },
-          userCredentials: {
-            apiKey: api_key,
-            email: email,
-            password: password 
-          }
-        }
+    OAUTH_SITE = 'https://secure.echosign.com'
+    AUTHORIZE_PATH = '/public/oauth'
+    TOKEN_PATH = '/oauth/token'
+    REFRESH_PATH = '/oauth/refresh'
+    REVOKE_PATH = '/oauth/revoke'
+
+    attr_reader :access_token, :refresh_token, :expires_at
+
+    # Builds an Credentials object
+    #
+    # @param client_id [String] Client ID
+    # @param client_secret [String] Client secret
+    #
+    # @return [Echosign::Credentials] Echosign OAuth2 wrapper object
+    def initialize(client_id, client_secret)
+      @client = OAuth2::Client.new(
+        client_id,
+        client_secret,
+        site: OAUTH_SITE,
+        authorize_url: AUTHORIZE_PATH,
+        token_url: TOKEN_PATH
       )
     end
 
+    # Build an authorization endpoint URL for EchoSign's OAuth2 provider
+    #
+    # @param redirect_uri [String] A secure URL to redirect the user afterward
+    # @param scope [String] Space delimited set of permissions to approve
+    # @param state [String] Any value; will be returned to the client afterward
+    #
+    # @return [Echosign::Credentials] Echosign OAuth2 wrapper object
+    #
+    # The redirect_uri must be specified on the app's OAuth Configuration page.
+    # @see https://secure.na1.echosign.com/public/static/oauthDoc.jsp#authorizationRequest
+    def authorize_url(redirect_uri, scope, state = nil)
+      return @client.auth_code.authorize_url(
+        redirect_uri: redirect_uri,
+        scope: scope,
+        state: state
+      )
+    end
+
+    # Make a request to the token endpoint and return an access token
+    #
+    # @param code [String] The authorization code obtained after #authorize_url
+    # @param redirect_uri [String] The redirect_url used during #authorize_url
+    #
+    # @return [String] An access token that can be used in the EchoSign API
+    def get_token(code, redirect_uri)
+      @client.options[:token_url] = TOKEN_PATH
+      oauth_token = @client.get_token(code: code,
+                                      redirect_uri: redirect_uri,
+                                      grant_type: :authorization_code)
+
+      @access_token = oauth_token.token
+      @refresh_token = oauth_token.refresh_token
+      @expires_at = oauth_token.expires_at
+
+      return @access_token
+    end
+
+    # Update (refresh) an access token
+    #
+    # @param current_refresh_token [String] A previously obtained refresh_token from a get_token request
+    #
+    # @return [String] A new access token to be used in the EchoSign API
+    #
+    # This method should only be called after #get_token
+    def refresh_access_token(current_refresh_token = nil)
+      @refresh_token = current_refresh_token if current_refresh_token != nil
+
+      @client.options[:token_url] = REFRESH_PATH
+      oauth_token = @client.get_token(grant_type: :refresh_token, refresh_token: @refresh_token)
+
+      @access_token = oauth_token.token
+      @expires_at = oauth_token.expires_at
+
+      return @access_token
+    end
+
+    # Revoke an access or refresh token, and any corresponding tokens
+    #
+    # @param which [Symbol] The token to revoke, either :access or :refresh
+    #
+    # @return [void]
+    def revoke_token(which = :access)
+      if which == :access
+        @client.request(:post, REVOKE_PATH, body: { token: @access_token })
+      else
+        @client.request(:post, REVOKE_PATH, body: { token: @refresh_token })
+        @refresh_token = nil
+      end
+
+      @access_token = nil
+      @expires_at = nil
+    end
   end
 end
-