echochamber 1.0.1

data/lib/echochamber/user.rb

@@ -0,0 +1,29 @@
+module Echochamber
+  class User < Hash
+
+    include Validatable
+
+    # Creates a user for the current application
+    #
+    # @param [Hash] params SYMBOL-referenced Hash containing:
+    # @option params [String] :email User's email address (REQUIRED)
+    # @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] :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
+    # @return [String] User ID
+
+    def initialize(params)
+      require_keys([:firstName, :lastName, :email, :password], params)
+      merge!(params)
+    end
+
+  end # class User
+end # module Echochamber

data/lib/echochamber/validatable.rb

@@ -0,0 +1,54 @@
+module Echochamber
+
+  class RequiredParameterError < StandardError; end
+  class ParameterError < StandardError; end
+
+  module Validatable
+
+    def require_keys(required_fields, params)
+      required_fields.each do |field|
+        validate_field(field, params) 
+      end
+    end
+
+    def require_exactly_one(field_group, params)
+      set_fields = 0
+      field_group.each do |field|
+        begin
+          validate_field(field, params) 
+        rescue RequiredParameterError
+          next
+        else
+          set_fields += 1
+        end
+      end
+      raise ParameterError, "Exactly one of #{field_group.to_s} should be present" if set_fields != 1
+    end
+
+    # TODO (kayagoban) A validator accepting a block for conditional execution
+    # might be useful.  
+    # Maybe require_keys should accept a block.  Figure out later.
+
+    def validate_field(field, params)
+      begin
+        value = params.fetch(field)
+        required_error(field) if value.nil? || value.empty?
+      rescue KeyError
+        required_error(field)
+      end
+    end
+
+    private
+
+    def required_error(field)
+      raise RequiredParameterError, "Nil, empty or missing required parameter: #{field.to_s}"
+    end
+
+    # If blank? did not exist, we would need to invent it.
+    def blank?(field)
+      field.nil? || field.empty? 
+    end
+
+  end
+
+end

data/lib/echochamber/version.rb

@@ -0,0 +1,3 @@
+module Echochamber
+  VERSION = "1.0.1"
+end

data/lib/echochamber/widget.rb

@@ -0,0 +1,42 @@
+require 'echochamber/widget/widget_completion_info'
+require 'echochamber/widget/widget_security_option'
+require 'echochamber/widget/widget_signer_security_option'
+require 'echochamber/widget/widget_vaulting_info'
+require 'echochamber/widget/widget_personalization'
+require 'echochamber/widget/widget_status'
+
+module Echochamber
+  class Widget < Hash
+
+    include Validatable
+
+    attr_reader :user_id, :user_email
+
+    # Widget initialization object
+    # 
+    # @param user_id [String] The ID of the user on whose behalf widget is being created.
+    # @param user_email [String] The email address of the user on whose behalf widget is being created. If both X-User-Id and X-User-Email are provided then X-User-Id is given preference. If neither is specified then the user is inferred from the access token.
+    # @param [Hash] params SYMBOL-referenced Hash containing: (REQUIRED)
+    # @option params [String] :name The name of the widget that will be used to identify it, in emails and on the website (REQUIRED)
+    # @option params [Array] :fileInfos Populate with instances of {Echochamber::Fileinfo Echochamber::Fileinfo}.  A list of one or more files (or references to files) that will be used to create the widget. If more than one file is provided, they will be combined before the widget is created. Library documents are not permitted. Note: Only one of the four parameters in every Fileinfo object must be specified (REQUIRED)
+    # @option param [String] :signatureFlow ['SENDER_SIGNATURE_NOT_REQUIRED' or 'SENDER_SIGNS_LAST']: 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 or SENDER_SIGNS_LAST (REQUIRED)
+    # @option params [Array] :formFieldLayerTemplates Populate with instances of {Echochamber::Fileinfo Echochamber::Fileinfo}.  Specifies the form field layer template or source of form fields to apply on the files in this transaction. If specified, the FileInfo for this parameter must refer to a form field layer template via libraryDocumentId or libraryDocumentName, or if specified via transientDocumentId or documentURL, it must be of a supported file type. Note: Only one of the four parameters in every FileInfo object must be specified. 
+    # @option params [Echochamber::WidgetCompletionInfo] :widgetCompletionInfo URL and associated properties for the success page the user will be taken to after filling out the widget 
+    # @option params [String] :callbackInfo A publicly accessible url to which EchoSign will perform an HTTP PUT operation with the final signed PDF file. HTTP authentication is supported using standard embedded syntax - i.e. http://username:password@your.server.com/path/to/file. EchoSign can also communicate with your system using HTTP GET, every time there is a new agreement event. Please contact support@echosign.com if you wish to use this option.
+    # @option params [Echochamber::WidgetSecurityOption] :securityOptions Sets optional secondary security parameters for your widget 
+    # @option params [String] :locale The locale associated with this widget - specifies the language for the signing page and emails, for example en_US or fr_FR. If none specified, defaults to the language configured for the widget creator
+    # @option params [Echochamber::CounterSignerInfo] :counterSigners A list of one or more counter signers
+    # @option params [Echochamber::WidgetVaultingInfo] :vaultingInfo Sets the vaulting properties that allows EchoSign to securely store documents with a vault provider
+    # @option params [Echochamber::WidgetMergefieldInfo] :mergeFieldInfo  Optional default values for fields to merge into the document. The values will be presented to the signers for editable fields; for read-only fields the provided values will not be editable during the signing process. Merging data into fields is currently not supported when used with libraryDocumentId or libraryDocumentName. Only file and url are curently supported
+    # @option params [Echochamber::WidgetCompletionInfo] :widgetAuthFailureInfo URL and associated properties for the error page the user will be taken after failing to authenticate 
+    # @option params [Echochamber::WidgetSignerSecurityOption] :widgetSignerSecurityOptions Security options that apply to widget signers
+    def initialize(user_id=nil, user_email=nil, params)
+      require_keys([:name, :fileInfos, :signatureFlow], params)
+      @user_id = user_id
+      @user_email = user_email
+      
+      merge!({ widgetCreationInfo: params })
+    end
+
+  end
+end

data/lib/echochamber/widget/client.rb

@@ -0,0 +1,127 @@
+module Echochamber
+
+  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 [Echochamber::Widget]
+    # @return [Hash]
+    def create_widget(widget)
+      Echochamber::Request.create_widget(token, widget)
+    end
+
+    # Personalize the widget to a signable document for a specific known user
+    # 
+    # @param widget_id
+    # @param personalization [Echochamber::WidgetPersonalization]
+    # @return [Hash] Operation result
+    def personalize_widget(widget_id, personalization)
+      Echochamber::Request.personalize_widget(token, widget_id, personalization)
+    end
+
+    # Enables or Disables a widget
+    # 
+    # @param widget_id
+    # @param status [Echochamber::WidgetStatus]
+    # @return [Hash] Widget status
+    def update_widget_status(widget_id, status)
+      Echochamber::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)
+      Echochamber::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)
+      Echochamber::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)
+      Echochamber::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 = Echochamber::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 = Echochamber::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 = Echochamber::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 = Echochamber::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/echochamber/widget/counter_signer_info.rb

@@ -0,0 +1,19 @@
+module Echochamber
+  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 {Echochamber::WidgetSignerSecurityOption Echochamber::WidgetSignerSecurityOption} Security options that apply to the counter signers
+    def initialize(params)
+      require_keys([:email, :role], params)
+      merge!(params)
+    end
+
+  end
+end

data/lib/echochamber/widget/request.rb

@@ -0,0 +1,135 @@
+module Echochamber::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 [Echochamber::Widget]
+  # @return [Hash]
+  def self.create_widget(token, widget)
+    endpoint = ENDPOINT.fetch(:widget) 
+    headers = { :content_type => :json, :accept => :json, '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 [Echochamber::WidgetPersonalization]
+  # @return [Hash] Response body
+  def self.personalize_widget(token, widget_id, personalization)
+    headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/personalize"
+
+    begin
+      response = RestClient.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 [Echochamber::WidgetStatus]
+  # @return [Hash] Response body
+  def self.update_widget_status(token, widget_id, status)
+    headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/status"
+
+    begin
+      response = RestClient.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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/formData"
+    response = get(endpoint, headers)
+  end
+
+
+
+
+end

data/lib/echochamber/widget/widget_completion_info.rb

@@ -0,0 +1,19 @@
+module Echochamber
+  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!(params)
+    end
+
+  end
+end
+

data/lib/echochamber/widget/widget_personalization.rb

@@ -0,0 +1,21 @@
+module Echochamber
+  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 [Echochamber::Validatable]
+    def initialize(params)
+      require_keys([:email], params)
+      merge!(params)
+    end
+
+  end
+end