echosign 1.0.2 → 1.5.0

data/lib/echosign/validatable.rb

@@ -1,13 +1,11 @@
 module Echosign
-
   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) 
+        validate_field(field, params)
       end
     end
 
@@ -15,18 +13,18 @@ module Echosign
       set_fields = 0
       field_group.each do |field|
         begin
-          validate_field(field, params) 
+          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
+      raise ParameterError, "Exactly one of #{field_group} should be present" if set_fields != 1
     end
 
     # TODO (bernardworthy) A validator accepting a block for conditional execution
-    # might be useful.  
+    # might be useful.
     # Maybe require_keys should accept a block.  Figure out later.
 
     def validate_field(field, params)
@@ -41,14 +39,12 @@ module Echosign
     private
 
     def required_error(field)
-      raise RequiredParameterError, "Nil, empty or missing required parameter: #{field.to_s}"
+      raise RequiredParameterError, "Nil, empty or missing required parameter: #{field}"
     end
 
     # If blank? did not exist, we would need to invent it.
     def blank?(field)
-      field.nil? || field.empty? 
+      field.nil? || field.empty?
     end
-
   end
-
 end

data/lib/echosign/version.rb

@@ -1,3 +1,3 @@
 module Echosign
-  VERSION = "1.0.2"
+  VERSION = "1.5.0"
 end

data/lib/echosign/widget.rb

@@ -7,31 +7,58 @@ require 'echosign/widget/widget_status'
 
 module Echosign
   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 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 {Echosign::Fileinfo Echosign::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 {Echosign::Fileinfo Echosign::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 [Echosign::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 [Echosign::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 [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 {Echosign::Fileinfo Echosign::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 {Echosign::Fileinfo
+    #   Echosign::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 [Echosign::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 [Echosign::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 [Echosign::CounterSignerInfo] :counterSigners A list of one or more counter signers
-    # @option params [Echosign::WidgetVaultingInfo] :vaultingInfo Sets the vaulting properties that allows EchoSign to securely store documents with a vault provider
-    # @option params [Echosign::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 [Echosign::WidgetCompletionInfo] :widgetAuthFailureInfo URL and associated properties for the error page the user will be taken after failing to authenticate 
-    # @option params [Echosign::WidgetSignerSecurityOption] :widgetSignerSecurityOptions Security options that apply to widget signers
-    def initialize(user_id=nil, user_email=nil, name, fileInfos, signatureFlow, widget_completion_info)
-      # require_keys([:name, :fileInfos, :signatureFlow], params)
+    # @option params [Echosign::WidgetVaultingInfo] :vaultingInfo Sets the vaulting properties that allows EchoSign
+    #   to securely store documents with a vault provider
+    # @option params [Echosign::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 [Echosign::WidgetCompletionInfo] :widgetAuthFailureInfo URL and associated properties for the
+    #   error page the user will be taken after failing to authenticate
+    # @option params [Echosign::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
 
@@ -161,16 +188,15 @@ module Echosign
       #     "signatureFlow": ""
       #   }
       # }
-      
-      merge!({ 
-        widgetCreationInfo: {
-          name: name,
-          fileInfos: fileInfos, 
-          signatureFlow: signatureFlow,
-          widgetCompletion_Info: widget_completion_info
-        }
-      })
-    end
 
+      merge!({
+               widgetCreationInfo: {
+                 name: params[:name],
+                 fileInfos: params[:fileInfos],
+                 signatureFlow: params[:signatureFlow],
+                 widgetCompletion_Info: params[:widget_completion_info]
+               }
+             })
+    end
   end
 end

data/lib/echosign/widget/client.rb

@@ -1,68 +1,70 @@
 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
-    # 
+    # 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)
+      request(:create_widget, 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)
+      request(:personalize_widget, 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)
+      request(:update_widget_status, 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
+    # @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)
+    def get_widgets(user_id = nil, user_email = nil)
+      request(:get_widgets, 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)
+      request(:get_widget, 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 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)
+    def get_widget_documents(widget_id, version_id = nil, participant_email = nil)
+      request(:get_widget_documents, 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)
+    def get_widget_document_file(widget_id, document_id, file_path = nil)
+      response = request(:get_widget_document_file, widget_id, document_id)
       unless file_path.nil?
         file = File.new(file_path, 'wb')
         file.write(response)
@@ -72,13 +74,13 @@ module Echosign
     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)
+    def get_widget_audit_trail(widget_id, file_path = nil)
+      response = request(:get_widget_audit_trail, widget_id)
       unless file_path.nil?
         file = File.new(file_path, 'wb')
         file.write(response)
@@ -88,13 +90,13 @@ module Echosign
     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)
+    def get_widget_combined_pdf(widget_id, file_path = nil)
+      response = request(:get_widget_combined_pdf, widget_id)
       unless file_path.nil?
         file = File.new(file_path, 'wb')
         file.write(response)
@@ -104,13 +106,13 @@ module Echosign
     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)
+    def get_widget_form_data(widget_id, file_path = nil)
+      response = request(:get_widget_form_data, widget_id)
       unless file_path.nil?
         file = File.new(file_path, 'wb')
         file.write(response)
@@ -118,10 +120,5 @@ module Echosign
       end
       response
     end
-
-
-
-
   end
 end
-

data/lib/echosign/widget/counter_signer_info.rb

@@ -1,19 +1,18 @@
 module Echosign
   class CounterSignerInfo < Hash
-
     include Validatable
 
     # Initialization object
-    # 
-    # @param [Hash] params SYMBOL-referenced Hash containing: 
+    #
+    # @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
+    # @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

@@ -1,15 +1,15 @@
 module Echosign::Request
-
-  # Creates a widget and returns the Javascript snippet and URL to access the widget and widgetID in response to the client
-  # 
+  # 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?
+  def self.create_widget(token, base_uri, widget)
+    endpoint = ENDPOINT.fetch(:widget, base_uri)
+    headers = { 'Access-Token' => token }
+    headers['X-User-Id'] = widget.user_id unless widget.user_id.nil?
+    headers['X-User-Email'] = widget.user_email unless widget.user_email.nil?
     response = post(endpoint, widget, headers)
     JSON.parse(response.body)
   end
@@ -20,20 +20,10 @@ module Echosign::Request
   # @param widget_id [String]
   # @param personalization [Echosign::WidgetPersonalization]
   # @return [Hash] Response body
-  def self.personalize_widget(token, widget_id, personalization)
+  def self.personalize_widget(token, base_uri, 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
-
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{widget_id}/personalize"
+    response = put(endpoint, personalization.to_json, headers)
     JSON.parse(response.body)
   end
 
@@ -43,20 +33,10 @@ module Echosign::Request
   # @param widget_id [String]
   # @param status [Echosign::WidgetStatus]
   # @return [Hash] Response body
-  def self.update_widget_status(token, widget_id, status)
+  def self.update_widget_status(token, base_uri, 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
-
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{widget_id}/status"
+    response = put(endpoint, status.to_json, headers)
     JSON.parse(response.body)
   end
 
@@ -66,11 +46,11 @@ module Echosign::Request
   # @param user_id [String]
   # @param user_email [String]
   # @return [Hash] Response body
-  def self.get_widgets(token, user_id=nil, user_email=nil)
+  def self.get_widgets(token, base_uri, 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)}"
+    headers['X-User-Id'] = user_id unless user_id.nil?
+    headers['X-User-Email'] = user_email unless user_email.nil?
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}"
     response = get(endpoint, headers)
     JSON.parse(response.body)
   end
@@ -79,9 +59,9 @@ module Echosign::Request
   #
   # @param widget_id [String]
   # @return [Hash] Response body
-  def self.get_widget(token, widget_id)
+  def self.get_widget(token, base_uri, widget_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}"
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{widget_id}"
     response = get(endpoint, headers)
     JSON.parse(response.body)
   end
@@ -90,9 +70,9 @@ module Echosign::Request
   #
   # @param widget_id [String]
   # @return [Hash] Response body
-  def self.get_widget_documents(token, widget_id, version_id=nil, participant_email=nil)
+  def self.get_widget_documents(token, base_uri, widget_id, version_id = nil, participant_email = nil)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/documents"
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{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)
@@ -103,9 +83,9 @@ module Echosign::Request
   #
   # @param widget_id [String]
   # @return [Hash] Response body
-  def self.get_widget_document_file(token, widget_id, document_id)
+  def self.get_widget_document_file(token, base_uri, widget_id, document_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/documents/#{document_id}"
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{widget_id}/documents/#{document_id}"
     response = get(endpoint, headers)
   end
 
@@ -113,9 +93,9 @@ module Echosign::Request
   #
   # @param widget_id [String]
   # @return [Hash] Response body
-  def self.get_widget_audit_trail(token, widget_id)
+  def self.get_widget_audit_trail(token, base_uri, widget_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/auditTrail"
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{widget_id}/auditTrail"
     response = get(endpoint, headers)
   end
 
@@ -123,13 +103,9 @@ module Echosign::Request
   #
   # @param widget_id [String]
   # @return [Hash] Response body
-  def self.get_widget_form_data(token, widget_id)
+  def self.get_widget_form_data(token, base_uri, widget_id)
     headers = { 'Access-Token' => token }
-    endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/formData"
+    endpoint = "#{ENDPOINT.fetch(:widget, base_uri)}/#{widget_id}/formData"
     response = get(endpoint, headers)
   end
-
-
-
-
 end