echosign 1.0.2

data/lib/echosign/widget/client.rb

@@ -0,0 +1,127 @@
+module Echosign
+
+  class Client
+
+    # Creates a widget and returns the Javascript snippet and URL to access the widget and widgetID in response to the client
+    # 
+    # @param widget [Echosign::Widget]
+    # @return [Hash]
+    def create_widget(widget)
+      Echosign::Request.create_widget(token, widget)
+    end
+
+    # Personalize the widget to a signable document for a specific known user
+    # 
+    # @param widget_id
+    # @param personalization [Echosign::WidgetPersonalization]
+    # @return [Hash] Operation result
+    def personalize_widget(widget_id, personalization)
+      Echosign::Request.personalize_widget(token, widget_id, personalization)
+    end
+
+    # Enables or Disables a widget
+    # 
+    # @param widget_id
+    # @param status [Echosign::WidgetStatus]
+    # @return [Hash] Widget status
+    def update_widget_status(widget_id, status)
+      Echosign::Request.update_widget_status(token, widget_id, status)
+    end
+
+    # Retrieves widgets for a user
+    # 
+    # @param user_id [String] The ID of the user whose widgets are being requested
+    # @param user_email [String] The email address of the user whose widgets are being requested. If both user_id  and user_email are provided then user_id is given preference. If neither is specified then the user is inferred from the access token
+    # @return [Hash] Widgets info
+    def get_widgets(user_id=nil, user_email=nil)
+      Echosign::Request.get_widgets(token, user_id, user_email)
+    end
+
+    # Retrieves the details of a widget
+    # 
+    # @param widget_id
+    # @return [Hash] Detailed widget info
+    def get_widget(widget_id)
+      Echosign::Request.get_widget(token, widget_id)
+    end
+
+    # Retrieves the IDs of the documents associated with widget.
+    # 
+    # @param widget_id [String]
+    # @param version_id [String] The version identifier of widget as provided by get_widget. If not provided then latest version will be used.
+    # @param participant_email [String] The email address of the participant to be used to retrieve documents
+    # @return [Hash] Info about widget documents
+    def get_widget_documents(widget_id, version_id=nil, participant_email=nil)
+      Echosign::Request.get_widget_documents(token, widget_id, version_id, participant_email)
+    end
+
+    # Retrieves the file stream of a document of a widget
+    # 
+    # @param widget_id [String]
+    # @param document_id [String]
+    # @param file_path [String] File path where to save the document.  If none is given, nothing will be saved to file.
+    # @return [String] Raw file stream
+    def get_widget_document_file(widget_id, document_id, file_path=nil)
+      response = Echosign::Request.get_widget_document_file(token, widget_id, document_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+    # Retrieves the audit trail of a widget identified by widgetId
+    # 
+    # @note SEEMINGLY NOT YET IMPLEMENTED SERVER-SIDE
+    # @param widget_id [String]
+    # @param file_path [String] File path where to save the document.  If none is given, nothing will be saved to file.
+    # @return [String] Raw file stream
+    def get_widget_audit_trail(widget_id, file_path=nil)
+      response = Echosign::Request.get_widget_audit_trail(token, widget_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+    # Gets a single combined PDF document for the documents associated with a widget.
+    # 
+    # @note SEEMINGLY NOT YET IMPLEMENTED SERVER-SIDE
+    # @param widget_id [String]
+    # @param file_path [String] File path where to save the document.  If none is given, nothing will be saved to file.
+    # @return [String] Raw file stream
+    def get_widget_combined_pdf(widget_id, file_path=nil)
+      response = Echosign::Request.get_widget_combined_pdf(token, widget_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+    # Retrieves data entered by the user into interactive form fields at the time they signed the widget
+    # 
+    # @note SEEMINGLY NOT YET IMPLEMENTED SERVER-SIDE
+    # @param widget_id [String]
+    # @param file_path [String] File path where to save the document.  If none is given, nothing will be saved to file.
+    # @return [String] Raw file stream
+    def get_widget_form_data(widget_id, file_path=nil)
+      response = Echosign::Request.get_widget_form_data(token, widget_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+
+
+
+  end
+end
+

data/lib/echosign/widget/counter_signer_info.rb

@@ -0,0 +1,19 @@
+module Echosign
+  class CounterSignerInfo < Hash
+
+    include Validatable
+
+    # Initialization object
+    # 
+    # @param [Hash] params SYMBOL-referenced Hash containing: 
+    # @option params [String] :email Email of the recipient (REQUIRED)
+    # @option params [String] :role ['SIGNER' or 'APPROVER']: Specify the role of recipient (REQUIRED)
+
+    # @option params [Array] :securityOptions Populate with instances of {Echosign::WidgetSignerSecurityOption Echosign::WidgetSignerSecurityOption} Security options that apply to the counter signers
+    def initialize(params)
+      require_keys([:email, :role], params)
+      merge!(params)
+    end
+
+  end
+end

data/lib/echosign/widget/request.rb

@@ -0,0 +1,135 @@
+module Echosign::Request
+
+  # Creates a widget and returns the Javascript snippet and URL to access the widget and widgetID in response to the client
+  # 
+  # @param token [String] Auth token
+  # @param widget [Echosign::Widget]
+  # @return [Hash]
+  def self.create_widget(token, widget)
+    endpoint = ENDPOINT.fetch(:widget) 
+    headers = { 'Access-Token' => token}
+    headers.merge!('X-User-Id' => widget.user_id) unless widget.user_id.nil?
+    headers.merge!('X-User-Email' => widget.user_email) unless widget.user_email.nil?
+    response = post(endpoint, widget, headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST PUT /agreement/:id operation
+  #
+  # @param token [String] Auth Token
+  # @param widget_id [String]
+  # @param personalization [Echosign::WidgetPersonalization]
+  # @return [Hash] Response body
+  def self.personalize_widget(token, widget_id, personalization)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/personalize"
+
+    begin
+      response = HTTParty.put(
+        endpoint, 
+        personalization.to_json,
+        headers
+      )
+    rescue Exception => error
+      raise_error(error)
+    end
+
+    JSON.parse(response.body)
+  end
+
+  # Performs REST PUT /agreement/:id operation
+  #
+  # @param token [String] Auth Token
+  # @param widget_id [String]
+  # @param status [Echosign::WidgetStatus]
+  # @return [Hash] Response body
+  def self.update_widget_status(token, widget_id, status)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/status"
+
+    begin
+      response = HTTParty.put(
+        endpoint, 
+        status.to_json,
+        headers 
+      )
+    rescue Exception => error
+      raise_error(error)
+    end
+
+    JSON.parse(response.body)
+  end
+
+  # Performs GET /widgets operation
+  #
+  # @param token [String] Auth Token
+  # @param user_id [String]
+  # @param user_email [String]
+  # @return [Hash] Response body
+  def self.get_widgets(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?
+    endpoint = "#{ENDPOINT.fetch(:widget)}"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs GET /widget operation
+  #
+  # @param widget_id [String]
+  # @return [Hash] Response body
+  def self.get_widget(token, widget_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs GET /widget/:id/documents operation
+  #
+  # @param widget_id [String]
+  # @return [Hash] Response body
+  def self.get_widget_documents(token, widget_id, version_id=nil, participant_email=nil)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/documents"
+    endpoint << add_query(endpoint, "versionId=#{version_id}") unless version_id.nil?
+    endpoint << add_query(endpoint, "participantEmail=#{participant_email}") unless participant_email.nil?
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs GET /widget/:id/documents/:id operation
+  #
+  # @param widget_id [String]
+  # @return [Hash] Response body
+  def self.get_widget_document_file(token, widget_id, document_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/documents/#{document_id}"
+    response = get(endpoint, headers)
+  end
+
+  # Performs GET /widget/:id/auditTrail
+  #
+  # @param widget_id [String]
+  # @return [Hash] Response body
+  def self.get_widget_audit_trail(token, widget_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/auditTrail"
+    response = get(endpoint, headers)
+  end
+
+  # Performs GET /widget/:id/formData
+  #
+  # @param widget_id [String]
+  # @return [Hash] Response body
+  def self.get_widget_form_data(token, widget_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/formData"
+    response = get(endpoint, headers)
+  end
+
+
+
+
+end

data/lib/echosign/widget/widget_completion_info.rb

@@ -0,0 +1,25 @@
+module Echosign
+  class WidgetCompletionInfo < Hash
+
+    include Validatable
+
+    # Widget initialization object
+    # 
+    # @param [Hash] params SYMBOL-referenced Hash containing:
+    # @option params [String] :url A publicly accessible url to which the user will be sent after successfully completing the widget. If the URL you provide includes information that allows you to identify the specific transaction, such as your own unique identifier, you can use the browser request to this URL as a callback to notify you that this transaction is completed. In addition, EchoSign will append a documentKey parameter to the URL which will contain the EchoSign DocumentKey for this signed widget, but only if the sender is the same as the API key user. Your application can use this value to get the form data for this widget. (REQUIRED)
+    # @option params [Boolean] :deframe If deframe is false, the success page will be shown inside the widget frame. If deframe is true, the success page will be shown in the full browser window. Note that if this widget is loaded through javascript returned from this end point, browser security restrictions do not permit automatic redirection in the full browser window, so if deframe is true the user will instead just see a link to the success page. We recommend this scenario be avoided - in other words, setting deframe to false is recommended for this case.
+    # @option params [Fixnum] :delay The delay (in seconds) before the user is taken to the success page. If this value is greater than 0, the user will first see the standard EchoSign success message, and then after a delay will be redirected to your success page. Note that this parameter has no effect for widgets loaded with javascript when deframe is true 
+    def initialize(params)
+      require_keys([:url])
+      merge!(
+      {
+        :deframe => deframe,
+        :delay => delay,
+        :url => url,
+      }
+      )
+    end
+
+  end
+end
+

data/lib/echosign/widget/widget_personalization.rb

@@ -0,0 +1,21 @@
+module Echosign
+  class WidgetPersonalization < Hash
+
+    include Validatable
+
+    # Initialization object
+    # 
+    # @option params [String] :email (string): The email address of the person who will be receiving this widget (REQUIRED)
+    # expiration (date, optional): Expiration date for the personalization of this widget. After this date, the identity of the signer will not be assumed by EchoSign.,
+    # @option params [String] :expiration Expiration date for the personalization of this widget. After this date, the identity of the signer will not be assumed by EchoSign. 
+    # @option params [String] :comment Comment describing how the API caller established the signer's identity - will appear in the audit trail.
+    # @option params [Boolean] :reusable Should the intended signer be allowed to sign this widget more than once
+    # @option params [Boolean] :allowManualVerification Not used at this time,
+    # @return [Echosign::Validatable]
+    def initialize(params)
+      require_keys([:email], params)
+      merge!(params)
+    end
+
+  end
+end

data/lib/echosign/widget/widget_security_option.rb

@@ -0,0 +1,22 @@
+module Echosign
+  class WidgetSecurityOption < Hash
+
+    include Validatable
+
+    # Widget initialization object
+    # 
+    # @param [Hash] params SYMBOL-referenced Hash containing:
+    # @option params [String] :passwordProtection Specifies if signers are required to enter a password to have access to sign the widget. The possible values are NONE, EXTERNAL_USERS, INTERNAL_USERS, or ALL_USERS
+    # @option params [String] :kbaProtection Signers need to pass Knowledge Based Authentication before they gain access to view and sign the widget. The possible values are NONE, EXTERNAL_USERS, INTERNAL_USERS, or ALL_USERS
+    # @option params [String] :webIdentityProtection Specifies if signers are required to provide their web identity, before they gain access to view and sign the widget. The possible values are NONE, EXTERNAL_USERS, INTERNAL_USERS, or ALL_USERS 
+    # @option params [Boolean] :protectOpen If set to true, the document is always be encrypted with this password every time it is sent by email. Recipients need to provide the password to be able to view the PDF files
+    # @option params [String] :internalPassword The secondary password that will be used to protect signing the widget for internal signers. Note that EchoSign will never show this password to anyone, so you will need to separately communicate it to any relevant parties. This password is applied only if password protection is specified for internal signers or all signers
+    # @option params [String] :externalPassword The secondary password that will be used to protect signing the widget for external signers. Note that EchoSign will never show this password to anyone, so you will need to separately communicate it to any relevant parties. This password is applied only if password protection is specified for external signers or all signers
+    # @option params [String] :openPassword The secondary password that will be used to secure the PDF document. Note that EchoSign will never show this password to anyone, so you will need to separately communicate it to any relevant parties. This password is used only if protectOpen field is set to true
+    def initialize(params)
+      merge!(params)
+    end
+
+  end
+end
+

data/lib/echosign/widget/widget_signer_security_option.rb

@@ -0,0 +1,18 @@
+module Echosign
+  class WidgetSignerSecurityOption < Hash
+
+    include Validatable
+
+    # Initialization object
+    # 
+    # @param [Hash] params SYMBOL-referenced Hash containing: 
+    # @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 widget. PHONE authentication is only applicable to counter signers but not to widget signer
+    # @option params [String] :password The password required for the recipient to view and sign the widget
+    # @option params [Array] :phoneInfos Populated with instances of [Echosign::PhoneInfo] The phoneInfo required for the counter signer to view and sign the widget if authentication method is PHONE. Not applicable to widget signer
+    def initialize(params)
+      require_keys([:authenticationMethod], params)
+      merge!(params)
+    end
+
+  end
+end

data/lib/echosign/widget/widget_status.rb

@@ -0,0 +1,20 @@
+module Echosign
+  class WidgetStatus< Hash
+
+    include Validatable
+
+    # Status object 
+    # 
+    # @option [Hash] params
+    # @option params [String] :value The status to which the widget is to be updated. The possible values for this variable are ENABLE and DISABLE (REQUIRED)
+    # @option params [String] :message Display this custom message to the user when the widget is accessed. Note that this can contain wiki markup to include clickable links in the message. This is required if redirectUrl is not provided. Both message and redirectUrl can not be specified
+    # @option params [String] :redirectUrl Redirect the user to this URL when the widget is accessed. This is required if message is not provided. Both message and redirectUrl can not be specified
+    # @return [Echosign::WidgetStatus]
+    def initialize(params)
+      require_keys([:value], params)
+      require_exactly_one([:message, :redirectUrl], params)
+      merge!(params)
+    end
+
+  end
+end

data/lib/echosign/widget/widget_vaulting_info.rb

@@ -0,0 +1,16 @@
+module Echosign
+  class WidgetVaultingInfo < Hash
+
+    include Validatable
+
+    # Initialization object
+    # 
+    # @param [Hash] params SYMBOL-referenced Hash containing: 
+    # @option params [Boolean] :enabled For accounts set up for document vaulting and the option to enable per agreement, this determines whether the document is to be vaulted
+    def initialize(params)
+      require_keys([:enabled], params)
+      merge!(params)
+    end
+
+  end
+end

data/spec/lib/agreement/client_spec.rb

@@ -0,0 +1,157 @@
+require 'spec_helper'
+
+require 'lib/shared_client.rb'
+
+describe Echosign::Client do
+  include_context "shared client"
+
+  describe '.create_agreement' do
+
+    let(:url_file_info) do
+      {
+      url: 'http://findgoplayers.com/resume.pdf',
+      mimeType: 'application/pdf',
+      name: 'resume.pdf'
+      }
+    end
+
+    let(:file_info) do
+      { 
+        documentURL: Echosign::UrlFileInfo.new(url_file_info) 
+      }
+    end
+
+    let(:file_infos) do
+      [ Echosign::Fileinfo.new(file_info) ] 
+    end
+
+    let(:agreement_user_id) { nil } 
+    let(:agreement_user_email) { nil }
+
+    let(:agreement_info) do
+      {
+        fileInfos: [ file_infos ],
+        recipients: [ Echosign::Recipient.new({ role: 'SIGNER', email: 'goishi.san@gmail.com'})],
+        signatureFlow: "SENDER_SIGNS_LAST",
+        signatureType: "ESIGN",
+        name: "Rumplestiltskin Contract"
+      }
+    end
+
+    let(:agreement)  { Echosign::Agreement.new(agreement_user_id, agreement_user_email, agreement_info) }
+
+    it 'returns the agreement_id' do
+      VCR.use_cassette('create_agreement', :record => :once) do
+        agreement_id = client.create_agreement(agreement)
+        expect(agreement_id).to_not be_nil
+      end
+    end
+  end
+
+  describe '.get_agreements' do
+    it 'returns all agreements' do
+      VCR.use_cassette('get_agreements', :record => :once) do
+        response = client.get_agreements
+        expect(response).to_not be_nil
+      end
+    end
+  end
+
+  describe '.agreement_info' do
+    let(:agreement_id) { "2AAABLblqZhA79nM-6ALjW2nXMKKb_ECz-Nr2yr_WrJ-3-Vz7d5D5_Dn9B6K-25C_EDktQqawW7M*" }
+    it 'returns detailed agreement info' do
+      VCR.use_cassette('agreement_info', :record => :once) do
+        response = client.agreement_info(agreement_id)
+        expect(response).to_not be_nil
+      end
+    end
+  end
+
+  describe '.agreement_form_data' do
+   let(:agreement_id) { "2AAABLblqZhDvfdYluvps8mSzQXnXr074OVtMYTwTVtljZYFJNi43iuzYeBaPUUOMTSlGXrt04Sw*" }
+    it 'returns CSV data' do
+      VCR.use_cassette('agreement_form_data', :record => :once) do
+        response = client.agreement_form_data(agreement_id)
+        expect(response).to_not be_nil
+      end
+   end
+  end
+
+  describe '.cancel_agreement' do
+    let(:agreement_id) { "2AAABLblqZhA79nM-6ALjW2nXMKKb_ECz-Nr2yr_WrJ-3-Vz7d5D5_Dn9B6K-25C_EDktQqawW7M*" }
+
+    it 'returns the result of the operation' do
+      VCR.use_cassette('cancel_agreement', :record => :once) do
+        result = client.cancel_agreement(agreement_id, true, 'Just because')
+        expect(result).to_not be_nil
+      end
+    end
+  end
+
+  describe '.agreement_documents' do
+    let(:agreement_id) { "2AAABLblqZhA79nM-6ALjW2nXMKKb_ECz-Nr2yr_WrJ-3-Vz7d5D5_Dn9B6K-25C_EDktQqawW7M*" }
+    let(:recipient_email) { 'goishi.san@gmail.com' }
+    let(:format) { 'CONVERTED_PDF' }
+    let(:version_id) { nil }
+
+    it 'returns information about documents for this agreement' do
+      VCR.use_cassette('agreement_documents', :record => :once) do
+        result = client.agreement_documents(agreement_id, recipient_email, format, version_id)
+        expect(result).to_not be_nil
+      end
+    end
+  end
+
+  describe '.agreement_document_file' do
+    let(:agreement_id) { "2AAABLblqZhA79nM-6ALjW2nXMKKb_ECz-Nr2yr_WrJ-3-Vz7d5D5_Dn9B6K-25C_EDktQqawW7M*" }
+    let(:document_id) { "2AAABLblqZhDcteEO9jy6gSat9d_3XgpPVpxhetoDCpU4L9PoolGv_3mqgKL1DhIGTXTHhqAHlHk*" }
+
+    it 'returns a document file from the selected agreement' do
+      VCR.use_cassette('agreement_document_file', :record => :once) do
+        result = client.agreement_document_file(agreement_id, document_id)
+        expect(result).to be_a String 
+        expect(result).to_not be_nil
+      end
+    end
+  end
+
+  describe '.audit_trail_pdf' do
+    let(:agreement_id) { "2AAABLblqZhA79nM-6ALjW2nXMKKb_ECz-Nr2yr_WrJ-3-Vz7d5D5_Dn9B6K-25C_EDktQqawW7M*" }
+
+    it 'returns a pdf file for an audit trail on the agreement' do
+      VCR.use_cassette('audit_trail_pdf', :record => :once) do
+        result = client.audit_trail_pdf(agreement_id)
+        expect(result).to be_a String 
+        expect(result).to_not be_nil
+      end
+    end
+  end
+
+  describe '.agreement_combined_pdf' do
+    let(:agreement_id) { "2AAABLblqZhA79nM-6ALjW2nXMKKb_ECz-Nr2yr_WrJ-3-Vz7d5D5_Dn9B6K-25C_EDktQqawW7M*" }
+
+    it 'returns a combined pdf file ' do
+      VCR.use_cassette('agreement_combined_pdf', :record => :once) do
+        result = client.agreement_combined_pdf(agreement_id)
+        expect(result).to be_a String 
+        expect(result).to_not be_nil
+      end
+    end
+  end
+
+  describe '.agreement_signing_urls' do
+    let(:agreement_id) { "2AAABLblqZhDdfTP0uM4EIz2UE2Mq27D7PXGl7Uk3e5nO4RtzlkN8GMANmeVwUVRWGGuUGCQoRQc*" }
+
+    it 'returns URL information for the agreement' do
+      VCR.use_cassette('agreement_signing_urls', :record => :once) do
+        result = client.agreement_signing_urls(agreement_id)
+        expect(result).to be_a Hash
+      end
+    end
+  end
+
+
+
+end
+ 
+