echosign 1.0.2

data/lib/echosign/mega_sign/request.rb

@@ -0,0 +1,144 @@
+module Echosign::Request
+
+  # Performs REST create_mega_sign 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] MegaSign response body
+  def self.create_mega_sign(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(:mega_sign), :body => body.to_json,
+    :headers => headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST GET /mega_signs operation
+  #
+  # @param token [String] Auth Token
+  # @return [Hash] MegaSigns response body
+  def self.get_mega_signs(token)
+    headers = { 'Access-Token' => token }
+    response = get(ENDPOINT.fetch(:mega_sign), headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST GET /mega_sign/:id operation
+  #
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
+  # @return [Hash] MegaSign info response body
+  def self.mega_sign_info(token, mega_sign_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Performs REST GET /mega_sign/:id/signingUrls operation
+  #
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
+  # @return [Hash] URL information for the eSign page of the mega_sign
+  def self.mega_sign_signing_urls(token, mega_sign_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/signingUrls"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Gets a single combined PDF document for the documents associated with an mega_sign.
+  # 
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
+  # @return [String] Raw bytes from document file
+  def self.mega_sign_combined_pdf(token, mega_sign_id, versionId, participantEmail, attachSupportingDocuments, auditReport)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_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 mega_sign
+  # 
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String]  (REQUIRED)
+  # @return [String] Raw bytes representing CSV file
+  def self.mega_sign_form_data(token, mega_sign_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/formData"
+    response = get(endpoint, headers)
+  end
+
+  # Retrieve mega_sign document PDF
+  #
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
+  # @return [String] Raw bytes from document file
+  def self.mega_sign_document_file(token, mega_sign_id, document_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/documents/#{document_id}"
+    response = get(endpoint, headers)
+  end
+
+  # Performs REST GET /mega_sign/:id/auditTrail operation
+  #
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
+  # @return [String] Raw bytes from audit pdf file
+  def self.audit_trail_pdf(token, mega_sign_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_id}/auditTrail"
+    response = get(endpoint, headers)
+  end
+
+  # Performs REST GET /mega_sign/:id/documents
+  #
+  # @param mega_sign_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 mega_sign as provided by {mega_sign_info mega_sign_info}.  If not provided, the latest version of the mega_sign is used.
+  # @return [Hash] MegaSign documents response body
+  def self.mega_sign_documents(token, mega_sign_id, recipient_email=nil, format=nil, version_id=nil)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_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 /mega_sign/:id operation
+  #
+  # @param token [String] Auth Token
+  # @param mega_sign_id [String] ID of mega_sign to retrieve info on.
+  # @param request_body [Hash] Hash for MegaSign status update
+  # @return [Hash] MegaSigns response body
+  def self.update_mega_sign_status(token, mega_sign_id, request_body)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:mega_sign)}/#{mega_sign_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

data/lib/echosign/refresh.rb

@@ -0,0 +1,25 @@
+module Echosign
+  class Refresh < Hash
+
+    include Validatable
+
+    # Builds a Credentials object
+    #
+    # @param client_id [String] Application key
+    # @param client_secret [String] Application secret
+    # @param refresh_token [String] OAuth Refresh Token
+    def initialize(client_id, client_secret, refresh_token)
+
+      merge!(
+      {
+        :client_id => client_id,
+        :client_secret => client_secret,
+        :refresh_token => refresh_token,
+        :grant_type => "refresh_token"
+      }
+      )
+    end
+
+  end
+end
+

data/lib/echosign/reminder.rb

@@ -0,0 +1,17 @@
+module Echosign
+  class Reminder < Hash
+
+    include Validatable
+
+    # Reminder options
+    #
+    # @param [Hash] params SYMBOL-referenced Hash containing exactly one of the following:
+    # @option params [String] :agreementId (REQUIRED)
+    # @option params [String] :comment An Optional message sent to the recipients, describing what is being sent and why their signatures are required.
+    # @return [Echosign::Reminder]
+    def initialize(params)
+      require_keys([:agreementId], params)
+      merge!(params)
+    end
+  end
+end

data/lib/echosign/request.rb

@@ -0,0 +1,165 @@
+require 'httparty'
+require 'echosign/agreement/request'
+require 'echosign/library_documents/request'
+require 'echosign/widget/request'
+
+module Echosign::Request
+  class Failure < StandardError
+    attr_reader :original_exception
+
+    def initialize msg, original_exception
+      @message = msg
+      @original_exception = original_exception
+    end
+  end
+
+  BASE_URL = 'https://api.eu1.echosign.com/api/rest/v5'
+  REFRESH_URL = 'https://api.eu1.echosign.com/oauth/refresh'
+
+  ENDPOINT = { 
+    token: BASE_URL + '/auth/tokens',
+    refresh: REFRESH_URL,
+    user: BASE_URL + '/users',
+    agreement: BASE_URL + '/agreements',
+    mega_sign: BASE_URL + '/megaSigns',
+    reminder: BASE_URL + '/reminders',
+    transientDocument: BASE_URL + '/transientDocuments',
+    libraryDocument: BASE_URL + '/libraryDocuments',
+    widget: BASE_URL + '/widgets'
+  }
+
+  # Retrieves the authentication token
+  #
+  # @param credentials [Echosign::Credentials] Initialized Echosign::Credentials
+  # @return [String] Valid authentication token
+  def self.get_token(credentials)
+    headers = {}
+    response = post(ENDPOINT.fetch(:token), credentials, headers)
+    response_body = JSON.parse(response.body)
+    response_body.fetch("access_token")
+  end
+
+  # Retrieves the authentication token
+  #
+  # @param credentials [Echosign::Credentials] Initialized Echosign::Credentials
+  # @return [String] Valid authentication token
+  def self.get_token_from_refresh(credentials)
+    # headers = { :content_type => "application/x-www-form-urlencoded" }
+    headers = {}
+    response = post(ENDPOINT.fetch(:refresh), credentials, headers)
+    response_body = JSON.parse(response.body)
+    response_body.fetch("access_token")
+  end
+
+  # Performs REST create_user operation
+  #
+  # @param body [Hash] Valid request body
+  # @param token [String] Auth Token
+  # @return [Hash] New user response body
+  def self.create_user(body, token)
+    endpoint = ENDPOINT.fetch(:user) 
+    headers = { 'Access-Token' => token}
+    response = post(endpoint, body, headers)
+    JSON.parse(response.body)
+  end
+  
+  # Sends a reminder for an agreement.
+  #
+  # @param body [Hash] Valid request body
+  # @param token [String] Auth Token
+  # @return [Hash] Response body
+  def self.create_reminder(token, body)
+  endpoint = ENDPOINT.fetch(:reminder)
+  headers = { 'Access-Token' => token}
+  response = post(endpoint, body, headers)
+  JSON.parse(response.body)
+  end
+
+  # Performs REST create_transient_document operation
+  #
+  # @param token [String] Auth token  (REQUIRED)
+  # @param file_name [String] File name  (REQUIRED)
+  # @param file_handle [File] File handle (REQUIRED)
+  # @param mime_type [String] Mime type
+  # @return [Hash] Transient Document Response Body
+  def self.create_transient_document(token, file_name, file_handle, mime_type=nil)
+    headers = { 'Access-Token' => token }
+
+    begin
+      response = HTTParty.post( 
+                                 ENDPOINT.fetch(:transientDocument), 
+                                 { 'File-Name' => file_name, 
+                                   'Mime-Type' => mime_type, 
+                                   'File' => file_handle,  
+                                   :multipart => true}, 
+                                   headers
+                                )
+    rescue Exception => error
+      raise_error(error)
+    end
+
+    JSON.parse(response.body)
+  end
+
+  # Gets all the users in an account that the caller has permissions to access. 
+  #
+  # @param token [String] Auth Token
+  # @param user_email [String] The email address of the user whose details are being requested.
+  # @return [Hash] User info hash
+  def self.get_users(token, user_email)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:user)}?x-user-email=#{user_email}"
+    response = get(endpoint, headers)
+    JSON.parse(response)
+  end
+
+  # Gets all the users in an account that the caller has permissions to access. 
+  #
+  # @param token [String] Auth Token
+  # @param user_id [String]
+  # @return [Hash] User info hash
+  def self.get_user(token, user_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:user)}/#{user_id}"
+    response = get(endpoint, headers)
+    JSON.parse(response)
+  end
+
+
+  private
+
+  def self.get(endpoint, headers)
+    begin
+      HTTParty.get(
+        endpoint, 
+        headers: headers
+      )
+    rescue Exception => error
+      raise_error(error)
+    end
+  end
+
+  def self.post(endpoint, body, headers)
+    begin
+      HTTParty.post(
+        endpoint,
+        query: body, 
+        headers: headers
+      )
+    rescue Exception => error
+      raise_error(error)
+    end
+  end
+
+  def self.add_query(url, query)
+    (url.include?('?') ? '&' : '?') + query
+  end
+
+  def self.raise_error(error)
+    puts error
+    message = "#{error.inspect}.  \nSee Adobe Echosign REST API documentation for Error code meanings: https://secure.echosign.com/public/docs/restapi/v5"
+    raise Failure.new message, error
+  end
+
+end
+

data/lib/echosign/user.rb

@@ -0,0 +1,29 @@
+module Echosign
+  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 Echosign

data/lib/echosign/validatable.rb

@@ -0,0 +1,54 @@
+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) 
+      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 (bernardworthy) 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.is_a?(String) && 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/echosign/version.rb

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

data/lib/echosign/widget.rb

@@ -0,0 +1,176 @@
+require 'echosign/widget/widget_completion_info'
+require 'echosign/widget/widget_security_option'
+require 'echosign/widget/widget_signer_security_option'
+require 'echosign/widget/widget_vaulting_info'
+require 'echosign/widget/widget_personalization'
+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 [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 [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)
+      @user_id = user_id
+      @user_email = user_email
+
+      # {
+      #   "widgetCreationInfo": {
+      #     "widgetCompletionInfo": {
+      #       "deframe": false,
+      #       "delay": 0,
+      #       "url": ""
+      #     },
+      #     "widgetAuthFailureInfo": {
+      #       "deframe": false,
+      #       "delay": 0,
+      #       "url": ""
+      #     },
+      #     "mergeFieldInfo": [
+      #       {
+      #         "fieldName": "",
+      #         "defaultValue": ""
+      #       }
+      #     ],
+      #     "formFieldLayerTemplates": [
+      #       {
+      #         "transientDocumentId": "",
+      #         "libraryDocumentId": "",
+      #         "libraryDocumentName": "",
+      #         "documentURL": {
+      #           "name": "",
+      #           "url": "",
+      #           "mimeType": ""
+      #         }
+      #       }
+      #     ],
+      #     "securityOptions": {
+      #       "passwordProtection": {
+      #         "ALL_USERS": "enum",
+      #         "EXTERNAL_USERS": "enum",
+      #         "NONE": "enum",
+      #         "INTERNAL_USERS": "enum"
+      #       },
+      #       "kbaProtection": {
+      #         "ALL_USERS": "enum",
+      #         "EXTERNAL_USERS": "enum",
+      #         "NONE": "enum",
+      #         "INTERNAL_USERS": "enum"
+      #       },
+      #       "webIdentityProtection": {
+      #         "ALL_USERS": "enum",
+      #         "EXTERNAL_USERS": "enum",
+      #         "NONE": "enum",
+      #         "INTERNAL_USERS": "enum"
+      #       },
+      #       "protectOpen": false,
+      #       "internalPassword": "",
+      #       "externalPassword": "",
+      #       "openPassword": ""
+      #     },
+      #     "fileInfos": [
+      #       {
+      #         "transientDocumentId": "",
+      #         "libraryDocumentId": "",
+      #         "libraryDocumentName": "",
+      #         "documentURL": {
+      #           "name": "",
+      #           "url": "",
+      #           "mimeType": ""
+      #         }
+      #       }
+      #     ],
+      #     "counterSignerSetInfos": [
+      #       {
+      #         "counterSignerSetRole": {
+      #           "SIGNER": "enum",
+      #           "DELEGATE_TO_SIGNER": "enum",
+      #           "DELEGATE_TO_APPROVER": "enum",
+      #           "APPROVER": "enum"
+      #         },
+      #         "counterSignerSetMemberInfos": [
+      #           {
+      #             "securityOptions": [
+      #               {
+      #                 "authenticationMethod": {
+      #                   "PHONE": "enum",
+      #                   "INHERITED_FROM_DOCUMENT": "enum",
+      #                   "KBA": "enum",
+      #                   "WEB_IDENTITY": "enum",
+      #                   "PASSWORD": "enum",
+      #                   "NONE": "enum"
+      #                 },
+      #                 "phoneInfos": [
+      #                   {
+      #                     "phone": "",
+      #                     "countryCode": ""
+      #                   }
+      #                 ],
+      #                 "password": ""
+      #               }
+      #             ],
+      #             "email": ""
+      #           }
+      #         ]
+      #       }
+      #     ],
+      #     "callbackInfo": "",
+      #     "widgetSignerSecurityOptions": {
+      #       "authenticationMethod": {
+      #         "PHONE": "enum",
+      #         "INHERITED_FROM_DOCUMENT": "enum",
+      #         "KBA": "enum",
+      #         "WEB_IDENTITY": "enum",
+      #         "PASSWORD": "enum",
+      #         "NONE": "enum"
+      #       },
+      #       "phoneInfos": [
+      #         {
+      #           "phone": "",
+      #           "countryCode": ""
+      #         }
+      #       ],
+      #       "password": ""
+      #     },
+      #     "name": "",
+      #     "locale": "",
+      #     "vaultingInfo": {
+      #       "enabled": false
+      #     },
+      #     "signatureFlow": ""
+      #   }
+      # }
+      
+      merge!({ 
+        widgetCreationInfo: {
+          name: name,
+          fileInfos: fileInfos, 
+          signatureFlow: signatureFlow,
+          widgetCompletion_Info: widget_completion_info
+        }
+      })
+    end
+
+  end
+end