echosign 1.0.2

data/fixtures/vcr_cassettes/personalize_widget.yml

@@ -0,0 +1,47 @@
+---
+http_interactions:
+- request:
+    method: put
+    uri: https://secure.echosign.com/api/rest/v5/widgets/2AAABLblqZhD_6RpgbZh5ZVlLXz1H1kfVzw4vHB91MtmjNHBDorFqO0H3_cGzBudZxiWNzPXFzOc*/personalize
+    body:
+      encoding: UTF-8
+      string: '{"email":"cthomas@railjumper.com"}'
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Content-Type:
+      - application/json
+      Access-Token:
+      - 2AAABLblqZhC3HrDExRuNnTr9I-U3z2f2KtGloHKah3ccogCP4HzbN5XSbcKSlxNJDtNCVAq94pM*
+      Content-Length:
+      - '34'
+      User-Agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Thu, 21 Aug 2014 04:23:18 GMT
+      Server:
+      - Apache
+      Content-Length:
+      - '382'
+      Strict-Transport-Security:
+      - max-age=31536000;
+      P3p:
+      - CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"
+      X-Robots-Tag:
+      - none
+      Content-Type:
+      - application/json;charset=UTF-8
+    body:
+      encoding: UTF-8
+      string: '{"javascript":"<script type=''text/javascript'' language=''JavaScript''
+        src=''https://secure.echosign.com/public/hostedForm?formid=9V5BHC4L3A394E&token=39QF96QTRUGYCPYUYQI0G4ZK''></script>","url":"https://secure.echosign.com/public/hostedForm?formid=9V5BHC4L3A394E&token=39QF96QTRUGYCPYUYQI0G4ZK","widgetId":"2AAABLblqZhD_6RpgbZh5ZVlLXz1H1kfVzw4vHB91MtmjNHBDorFqO0H3_cGzBudZxiWNzPXFzOc*"}'
+    http_version: 
+  recorded_at: Thu, 21 Aug 2014 04:23:18 GMT
+recorded_with: VCR 2.8.0

data/fixtures/vcr_cassettes/update_widget_status.yml

@@ -0,0 +1,46 @@
+---
+http_interactions:
+- request:
+    method: put
+    uri: https://secure.echosign.com/api/rest/v5/widgets/2AAABLblqZhD_6RpgbZh5ZVlLXz1H1kfVzw4vHB91MtmjNHBDorFqO0H3_cGzBudZxiWNzPXFzOc*/status
+    body:
+      encoding: UTF-8
+      string: '{"value":"DISABLE","message":"Hey guys, hope you like this widget."}'
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Content-Type:
+      - application/json
+      Access-Token:
+      - 2AAABLblqZhC3HrDExRuNnTr9I-U3z2f2KtGloHKah3ccogCP4HzbN5XSbcKSlxNJDtNCVAq94pM*
+      Content-Length:
+      - '68'
+      User-Agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Date:
+      - Thu, 21 Aug 2014 05:04:32 GMT
+      Server:
+      - Apache
+      Content-Length:
+      - '62'
+      Strict-Transport-Security:
+      - max-age=31536000;
+      P3p:
+      - CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"
+      X-Robots-Tag:
+      - none
+      Content-Type:
+      - application/json;charset=UTF-8
+    body:
+      encoding: UTF-8
+      string: '{"code":"OK","message":"The operation completed successfully"}'
+    http_version: 
+  recorded_at: Thu, 21 Aug 2014 05:04:32 GMT
+recorded_with: VCR 2.8.0

data/lib/echosign.rb

@@ -0,0 +1,11 @@
+require 'json'
+require "echosign/version"
+require 'echosign/client'
+require 'echosign/validatable'
+require 'echosign/credentials'
+require 'echosign/refresh'
+require 'echosign/request'
+require 'echosign/agreement'
+require 'echosign/user'
+require 'echosign/reminder'
+require 'echosign/widget'

data/lib/echosign/agreement.rb

@@ -0,0 +1,34 @@
+require 'echosign/agreement/fileinfo'
+require 'echosign/agreement/url_file_info'
+require 'echosign/agreement/recipient'
+require 'echosign/agreement/request_form_field'
+require 'echosign/agreement/form_field_location'
+
+module Echosign
+  class Agreement < Hash
+
+    include Validatable
+
+    attr_accessor :user_id, :user_email
+
+    # Creates an agreement object for submission
+    #
+    # @param [String] user_id ID of the user whom this agreement is made for
+    # @param [String] user_email Email of the user whom this agreement is made for
+    # @param [Hash] params SYMBOL-referenced Hash containing:
+    # @option params [Array] :fileInfos A list of one or more files (or references to files) that will be sent out for signature. If more than one file is provided, they will be combined into one PDF before being sent out. Note: Only one of the four parameters in every FileInfo object must be specified.  Populate the array with instances of {Echosign::Fileinfo Echosign::Fileinfo} (REQUIRED)
+    # @option params [Array] :recipientSetInfos A list of one or more recipients. For regular (non-MegaSign) documents, there is no limit on the number of electronic signatures in a single document. Written signatures are limited to four per document. This limit includes the sender if the sender's signature is also required.  Populate the array with instances of {Echosign::Recipient Echosign::Recipient} (REQUIRED)
+    # @option params [String] :signatureFlow ['SENDER_SIGNATURE_NOT_REQUIRED' or 'SENDER_SIGNS_LAST' or 'SENDER_SIGNS_FIRST' or 'SEQUENTIAL' or 'PARALLEL']: Selects the workflow you would like to use - whether the sender needs to sign before the recipient, after the recipient, or not at all. The possible values for this variable are SENDER_SIGNATURE_NOT_REQUIRED, SENDER_SIGNS_LAST, SENDER_SIGNS_FIRST, SEQUENTIAL or PARALLEL.  (REQUIRED)
+    # @option params [String] :signatureType ['ESIGN' or 'WRITTEN']: Specifies the type of signature you would like to request - written or eSignature. The possible values are ESIGN or WRITTEN  (REQUIRED)
+    # @option params [String] :name The name of the agreement that will be used to identify it, in emails and on the website. (REQUIRED)
+    # @return [Echosign::Agreement] 
+    def initialize(user_id=nil, user_email=nil, params)
+      @user_id = user_id
+      @user_email = user_email
+      #TODO (cthomas) barf if user_id or user_email are blank
+      require_keys([:signatureType, :recipientSetInfos, :signatureFlow, :fileInfos, :name], params)
+      merge!({ documentCreationInfo: params })
+    end
+
+  end # class Agreement
+end # module Echosign

data/lib/echosign/agreement/client.rb

@@ -0,0 +1,118 @@
+module Echosign
+
+  class Client
+
+   # Creates an agreement
+   #
+   # @param agreement [Echosign::Agreement]
+   # @return [String] Agreement ID
+   def create_agreement(agreement)
+      agreement_response = Echosign::Request.create_agreement(agreement, token, agreement.user_id, agreement.user_email)
+      agreement_response.fetch("agreementId")
+   end
+
+   # Gets list of agreements
+   #
+   # @param agreement [Echosign::Agreement]
+   # @return [String] Agreement ID
+   def get_agreements
+     get_agreements_response = Echosign::Request.get_agreements(token)
+     get_agreements_response.fetch("userAgreementList")
+   end
+
+   # Gets detailed info on an agreement
+   # 
+   # @param agreement_id [String] ID of agreement to retrieve info on.
+   # @return [Hash] Detailed agreement info
+   def agreement_info(agreement_id)
+     Echosign::Request.agreement_info(token, agreement_id)
+   end
+
+   # Cancel agreement
+   # 
+   # @param agreement_id [String] (REQUIRED)
+   # @param notify_signer [Boolean] Whether to notify the signer by email of the cancellation.  Default is false.
+   # @param comment [String] Comment regarding this cancellation.
+   # @return [String] Result of the operation
+   def cancel_agreement(agreement_id, notify_signer=false, comment=nil)
+     request_body = {
+       "value" => "CANCEL",
+       "notifySigner" => notify_signer 
+     }
+     request_body.merge!(comment: comment) unless comment.nil?
+
+     agreement_status_response = Echosign::Request.update_agreement_status(token, agreement_id, request_body)
+     agreement_status_response.fetch('result')
+   end
+
+   # All documents relating to an agreement
+   # 
+   # @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().  If not provided, the latest version of the agreement is used.
+   # @return [Array] Documents relating to agreement.
+   def agreement_documents(agreement_id, recipient_email, format, version_id=nil)
+     result = Echosign::Request.agreement_documents(token, agreement_id, recipient_email, format, version_id)
+   end
+
+   # Retrieve a document file from an agreement
+   #
+   # @param agreement_id [String]  (REQUIRED)
+   # @param document_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 agreement_document_file(agreement_id, document_id, file_path=nil)
+     response = Echosign::Request.agreement_document_file(token, agreement_id, document_id)
+     unless file_path.nil?
+       file = File.new(file_path, 'wb')
+       file.write(response)
+       file.close
+     end
+     response
+   end
+
+   # Retrieves the URL for the eSign page for the current signer(s) of an agreement
+   #
+   # @param agreement_id [String]  (REQUIRED)
+   # @return [Hash] URL information for the eSign page of the agreement
+   def agreement_signing_urls(agreement_id)
+     response = Echosign::Request.agreement_signing_urls(token, agreement_id)
+   end
+
+   # Gets a single combined PDF document for the documents associated with an agreement.
+   # 
+   # @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.
+   # @param versionId [String] The version identifier of agreement as provided by get_agreement. If not provided then latest version will be used
+   # @param participantEmail [String] The email address of the participant to be used to retrieve documents.  If none is given, the auth token will be used to determine the user
+   # @param attachSupportingDocuments [Boolean] When set to YES, attach corresponding supporting documents to the signed agreement PDF. Default value of this parameter is true.
+   # @param auditReport [Boolean] When set to YES, attach an audit report to the signed agreement PDF. Default value is false
+   # @return [String] Raw bytes from document file
+   def agreement_combined_pdf(agreement_id, file_path=nil, versionId=nil, participantEmail=nil, attachSupportingDocuments=true, auditReport=false)
+     response = Echosign::Request.agreement_combined_pdf(token, agreement_id, versionId, participantEmail, attachSupportingDocuments, auditReport)
+     unless file_path.nil?
+       file = File.new(file_path, 'wb')
+       file.write(response)
+       file.close
+     end
+     response
+   end
+
+   # Retrieves library document audit trail file
+   # 
+   # @param agreement_id [String]  (REQUIRED)
+   # @param file_path [String] File path where to save the CSV file.  If no file path is given, nothing is saved to disk.
+   # @return [String] Raw bytes representing CSV file
+   def agreement_form_data(agreement_id, file_path=nil)
+     response = Echosign::Request.agreement_form_data(token, agreement_id)
+     unless file_path.nil?
+       file = File.new(file_path, 'wb')
+       file.write(response)
+       file.close
+     end
+     response
+   end
+
+  end
+end

data/lib/echosign/agreement/fileinfo.rb

@@ -0,0 +1,20 @@
+module Echosign
+  class Fileinfo < Hash
+
+    include Validatable
+
+    # 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
+    # @option params [String] :libraryDocumentId A library document ID available to the sender
+    # @option params [String] :libraryDocumentName A library document name available to the sender
+    # @option params [Echosign::UrlFileInfo] :documentURL A description of the URL where the document can be found
+    # @return [Echosign::Fileinfo]
+    def initialize(params)
+      require_exactly_one([:transientDocumentId, :libraryDocumentId, :libraryDocumentName, :documentURL], params)
+      merge!(params)
+    end
+  end
+end
+

data/lib/echosign/agreement/form_field_location.rb

@@ -0,0 +1,20 @@
+module Echosign
+  class FormFieldLocation < Hash
+
+    include Validatable
+
+    # 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,
+    # @option param [Integer] left (double): No. of pixels from left of the page for form field placement,
+    # @option param [Integer] pageNumber (int): Number of the page where form field has to be placed, starting from 1.,
+    # @option param [Integer] top (double): No. of pixels from bottom of the page for form field placement,
+    # @option param [Integer] width (double): Width of the form field in pixels
+    # @return [Echosign::FormFieldLocation]
+    def initialize(params)
+      require_keys([:pageNumber, :left, :top, :width, :height], params)
+      merge!(params)
+    end
+  end
+end

data/lib/echosign/agreement/phone_info.rb

@@ -0,0 +1,19 @@
+module Echosign
+  class PhoneInfo < Hash
+
+    include Validatable
+
+    # 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
+    # @return [Echosign::PhoneInfo]
+
+    def initialize(params)
+      require_keys([:phone], params)
+      merge!(params)
+    end
+
+  end
+end

data/lib/echosign/agreement/recipient.rb

@@ -0,0 +1,22 @@
+module Echosign
+  class Recipient < Hash
+
+    include Validatable
+
+    # 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}
+    # @return [Echosign::Recipient]
+
+    def initialize(params)
+      require_exactly_one([:email, :fax], params)
+      merge!(params)
+    end
+
+  end
+end
+

data/lib/echosign/agreement/recipient_security_option.rb

@@ -0,0 +1,20 @@
+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] :password The password required for the recipient to view and sign the document.
+    # @return [Echosign::RecipientSecurityOption]
+
+    def initialize(params)
+      require_keys([:authenticationMethod], params)
+      merge! params
+    end
+
+  end
+end

data/lib/echosign/agreement/request.rb

@@ -0,0 +1,144 @@
+module Echosign::Request
+
+  # Performs REST create_agreement operation
+  #
+  # @param body [Hash] Request body  (REQUIRED)
+  # @param token [String] Auth token  (REQUIRED)
+  # @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)
+    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)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST GET /agreements operation
+  #
+  # @param token [String] Auth Token
+  # @return [Hash] Agreements response body
+  def self.get_agreements(token)
+    headers = { 'Access-Token' => token }
+    response = get(ENDPOINT.fetch(:agreement), headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST GET /agreement/:id operation
+  #
+  # @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)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST GET /agreement/:id/signingUrls operation
+  #
+  # @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)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{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)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{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)
+  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)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/formData"
+    response = get(endpoint, headers)
+  end
+
+  # Retrieve agreement document PDF
+  #
+  # @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)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/documents/#{document_id}"
+    response = get(endpoint, headers)
+  end
+
+  # Performs REST GET /agreement/:id/auditTrail operation
+  #
+  # @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)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/auditTrail"
+    response = get(endpoint, headers)
+  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.
+  # @return [Hash] Agreement documents response body
+  def self.agreement_documents(token, agreement_id, recipient_email=nil, format=nil, version_id=nil)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:agreement)}/#{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?
+    response = get(endpoint, headers)
+    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)
+    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
+
+    JSON.parse(response.body)
+  end
+
+
+end