echosign 1.0.2

data/lib/echosign/agreement/request_form_field.rb

@@ -0,0 +1,15 @@
+module Echosign
+  class RequestFormField < Hash
+
+    include Validatable
+
+    # Validates RequestFormField params 
+    #
+    # @param [Hash] params SYMBOL-referenced Hash containing exactly one of the following:
+    # @return [Echosign::RequestFormField]
+    def initialize(params)
+      require_keys([:locations, :name], params)
+      merge!(params)
+    end
+  end
+end

data/lib/echosign/agreement/url_file_info.rb

@@ -0,0 +1,18 @@
+module Echosign
+  class UrlFileInfo < Hash
+
+    include Validatable
+
+    # Validates UrlFileInfo parameters
+    #
+    # @param [Hash] params SYMBOL-referenced Hash 
+    # @option params [String] :url A publicly accessible URL for retrieving the raw file content. HTTP authentication is supported using standard embedded syntax - i.e. http://username:password@your.server.com/path/to/file (REQUIRED)
+    # @option params [String] :mimeType The mime type of the referenced file, used to determine if the file can be accepted and the necessary conversion steps can be performed.
+    # @option params [String] :name The original system file name of the document being sent - used to name attachments, and to infer the mime type if one is not explicitly specified
+    def initialize(params)
+      require_keys([:url], params)
+      merge! params
+    end
+  end
+end
+

data/lib/echosign/client.rb

@@ -0,0 +1,82 @@
+require 'echosign/agreement/client'
+require 'echosign/library_documents/client'
+require 'echosign/widget/client'
+
+
+module Echosign
+
+  class Client 
+
+    attr_reader :token
+    # Initializes the Client object
+    #
+    # @param credentials [Echosign::Credentials] Initialized Echosign::Credentials
+    # @return [Echosign::Client] Initialized Echosign::Client 
+    def initialize(credentials)
+      @token = Echosign::Request.get_token_from_refresh(credentials)
+    end
+
+    # Creates a user for the current application
+    #
+    # @param user [Echosign::User]
+    # @return [String] User ID of new Echosign user
+    def create_user(user)
+      user_response  = Echosign::Request.create_user(user, token)
+      user_response.fetch("userId")
+    end
+
+    # Creates a reminder 
+    #
+    # @param reminder [Echosign::Reminder]
+    # @return [String] Reminder ID
+    def create_reminder(reminder)
+      reminder_response = Echosign::Request.create_reminder(token, reminder)
+    end
+
+    # Creates a transient document for later referral
+    #
+    # @param file_name [String] 
+    # @param mime_type [String] 
+    # @param file_handle [File] 
+    # @return [String] Transient document ID
+    def create_transient_document(file_name, mime_type, file_handle)
+      transient_document_response = Echosign::Request.create_transient_document(token, file_name, file_handle, mime_type)
+      transient_document_response.fetch("transientDocumentId")
+    end
+
+    # Retrieve a PDF audit file for an agreement
+    #
+    # @param agreement_id [String]  (REQUIRED)
+    # @param file_path [String] File path to save the document.  If no file path is given, nothing is saved to disk.
+    # @return [String] Raw bytes from document file
+    def audit_trail_pdf(agreement_id, file_path=nil)
+      response = Echosign::Request.audit_trail_pdf(token, agreement_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+
+    # Gets all the users in an account that the caller has permissions to access.
+    # 
+    # @param user_email [String] The email address of the user whose details are being requested  (REQUIRED)
+    # @return [Hash] User info hash
+    def get_users(user_email)
+      Echosign::Request.get_users(token, user_email)
+    end
+
+    # Gets all the users in an account that the caller has permissions to access.
+    # 
+    # @param user_id [String]
+    # @return [Hash] User info hash
+    def get_user(user_id)
+      Echosign::Request.get_user(token, user_id)
+    end
+
+
+  end # class Client 
+
+end # module Echosign

data/lib/echosign/credentials.rb

@@ -0,0 +1,33 @@
+module Echosign
+  class Credentials < Hash
+
+    include Validatable
+
+    # Builds a Credentials object
+    #
+    # @param app_id [String] Application key
+    # @param app_secret [String] Application secret
+    # @param api_key [String] API Key
+    # @param email [String] User email 
+    # @param password [String] User password
+    # @return [Echosign::Credentials] Echosign credentials
+    def initialize(app_id, app_secret, api_key, email, password)
+
+      merge!(
+        {
+          applicationCredentials:  {
+          applicationId: app_id,
+          applicationSecret: app_secret
+        },
+          userCredentials: {
+            apiKey: api_key,
+            email: email,
+            password: password 
+          }
+        }
+      )
+    end
+
+  end
+end
+

data/lib/echosign/library_documents/client.rb

@@ -0,0 +1,83 @@
+module Echosign
+
+  class Client 
+
+    # Retrieves library documents metadata for a user.
+    #
+    # @param user_id [String] The ID of the user whose library documents are being requested. 
+    # @param user_email [String] The email address of the user whose library documents 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] Library documents metadata
+    def get_library_documents(user_id=nil, user_email=nil)
+      Echosign::Request.get_library_documents(token, user_id, user_email)
+    end
+
+    # Retrieves library document metadata 
+    #
+    # @param library_document_id [String] (REQUIRED)
+    # @return [Hash] Library document metadata
+    def get_library_document(library_document_id)
+      Echosign::Request.get_library_document(token, library_document_id)
+    end
+
+    # Retrieves library document files metadata
+    #
+    # @param library_document_id [String] (REQUIRED)
+    # @return [Hash] Library document files metadata
+    def get_library_document_files(library_document_id)
+      Echosign::Request.get_library_document_files(token, library_document_id)
+    end
+
+    # Retrieves library document file data
+    #
+    # @param library_document_id (REQUIRED)
+    # @param file_id [String] (REQUIRED)
+    # @param file_path [String] File path for saving the document.  If none is given, nothing will be saved to disk.
+    # @return [String] Raw library document file data
+    def get_library_document_file(library_document_id, file_id, file_path=nil)
+      response = Echosign::Request.get_library_document_file(token, library_document_id, file_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+    # Retrieves library document audit trail file
+    #
+    # @param library_document_id (REQUIRED)
+    # @param file_path [String] File path for saving the document.  If none is given, nothing will be saved to disk.
+    # @return [String] Raw library document file data
+    def library_document_audit_trail(library_document_id, file_path=nil)
+      response = Echosign::Request.library_document_audit_trail(token, library_document_id)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+    # Retrieves library combined document file
+    #
+    # @param library_document_id (REQUIRED)
+    # @param file_path [String] File path for saving the document.  If none is given, nothing will be saved to disk.
+    # @param auditReport [Boolean] When set to YES attach an audit report to the library document PDF. Default value will be false.
+    # @return [String] Raw library combined document file data
+    def library_combined_document(library_document_id, file_path=nil, auditReport=false)
+      response = Echosign::Request.library_combined_document(token, library_document_id, auditReport)
+      unless file_path.nil?
+        file = File.new(file_path, 'wb')
+        file.write(response)
+        file.close
+      end
+      response
+    end
+
+
+
+
+  end
+end
+
+

data/lib/echosign/library_documents/request.rb

@@ -0,0 +1,78 @@
+module Echosign::Request
+
+  # Retrieves library documents for a user.
+  #
+  # @param token [String] Auth Token
+  # @param user_id [String] The ID of the user whose library documents are being requested. 
+  # @param user_email [String] The email address of the user whose library documents 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] Library documents metadata
+  def self.get_library_documents(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(:libraryDocument)
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Retrieves library document metadata for a user.
+  #
+  # @param token [String] Auth Token
+  # @param library_document_id [String]
+  # @return [Hash] Library document metadata
+  def self.get_library_document(token, library_document_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Retrieves library document file
+  #
+  # @param token [String] Auth Token
+  # @param library_document_id [String] (REQUIRED)
+  # @return [Hash] Library document files metadata
+  def self.get_library_document_files(token, library_document_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/documents"
+    response = get(endpoint, headers)
+    JSON.parse(response.body)
+  end
+
+  # Retrieves library document file data
+  #
+  # @param token [String] Auth Token
+  # @param library_document_id [String] (REQUIRED)
+  # @param file_id [String] (REQUIRED)
+  # @return [String] Library document file data
+  def self.get_library_document_file(token, library_document_id, file_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/documents/#{file_id}"
+    response = get(endpoint, headers)
+  end
+
+  # Retrieves library document file data
+  #
+  # @param token [String] Auth Token
+  # @param library_document_id [String] (REQUIRED)
+  # @return [String] Library document file data
+  def self.library_document_audit_trail(token, library_document_id)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/auditTrail"
+    response = get(endpoint, headers)
+  end
+
+  # Retrieves library combined document file
+  #
+  # @param token [String] Auth Token
+  # @param library_document_id [String] (REQUIRED)
+  # @return [String] Raw library combined document file data
+  def self.library_combined_document(token, library_document_id, auditReport)
+    headers = { 'Access-Token' => token }
+    endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/combinedDocument"
+    endpoint << add_query(endpoint, "auditReport=#{auditReport}") 
+    response = get(endpoint, headers)
+  end
+
+end
+

data/lib/echosign/mega_sign.rb

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

data/lib/echosign/mega_sign/client.rb

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