echochamber 1.0.1

data/lib/echochamber/agreement/url_file_info.rb

@@ -0,0 +1,18 @@
+module Echochamber
+  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/echochamber/client.rb

@@ -0,0 +1,82 @@
+require 'echochamber/agreement/client'
+require 'echochamber/library_documents/client'
+require 'echochamber/widget/client'
+
+
+module Echochamber
+
+  class Client 
+
+    attr_reader :token
+    # Initializes the Client object
+    #
+    # @param credentials [Echochamber::Credentials] Initialized Echochamber::Credentials
+    # @return [Echochamber::Client] Initialized Echochamber::Client 
+    def initialize(credentials)
+      @token = Echochamber::Request.get_token(credentials)
+    end
+
+    # Creates a user for the current application
+    #
+    # @param user [Echochamber::User]
+    # @return [String] User ID of new Echosign user
+    def create_user(user)
+      user_response  = Echochamber::Request.create_user(user, token)
+      user_response.fetch("userId")
+    end
+
+    # Creates a reminder 
+    #
+    # @param reminder [Echochamber::Reminder]
+    # @return [String] Reminder ID
+    def create_reminder(reminder)
+      reminder_response = Echochamber::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 = Echochamber::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 = Echochamber::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)
+      Echochamber::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)
+      Echochamber::Request.get_user(token, user_id)
+    end
+
+
+  end # class Client 
+
+end # module Echochamber

data/lib/echochamber/credentials.rb

@@ -0,0 +1,33 @@
+module Echochamber
+  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 [Echochamber::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/echochamber/library_documents/client.rb

@@ -0,0 +1,83 @@
+module Echochamber
+
+  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)
+      Echochamber::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)
+      Echochamber::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)
+      Echochamber::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 = Echochamber::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 = Echochamber::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 = Echochamber::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/echochamber/library_documents/request.rb

@@ -0,0 +1,78 @@
+module Echochamber::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)
+  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)
+  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)
+  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/echochamber/reminder.rb

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

data/lib/echochamber/request.rb

@@ -0,0 +1,141 @@
+require 'rest-client'
+require 'echochamber/agreement/request'
+require 'echochamber/library_documents/request'
+require 'echochamber/widget/request'
+
+module Echochamber::Request
+  class Failure < StandardError; end
+
+  BASE_URL = 'https://secure.echosign.com/api/rest/v2'
+
+  ENDPOINT = { 
+    token: BASE_URL + '/auth/tokens',
+    user: BASE_URL + '/users',
+    agreement: BASE_URL + '/agreements',
+    reminder: BASE_URL + '/reminders',
+    transientDocument: BASE_URL + '/transientDocuments',
+    libraryDocument: BASE_URL + '/libraryDocuments',
+    widget: BASE_URL + '/widgets'
+  }
+
+  # Retrieves the authentication token
+  #
+  # @param credentials [Echochamber::Credentials] Initialized Echochamber::Credentials
+  # @return [String] Valid authentication token
+  def self.get_token(credentials)
+    headers = { :content_type => :json, :accept => :json  }
+    response = post(ENDPOINT.fetch(:token), credentials, headers)
+    response_body = JSON.parse(response.body)
+    response_body.fetch("accessToken")
+  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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, '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 = { :content_type => :json, :accept => :json, 'Access-Token' => token }
+
+    begin
+      response = RestClient.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
+      RestClient.get(
+        endpoint, 
+        headers
+      )
+    rescue Exception => error
+      raise_error(error)
+    end
+  end
+
+  def self.post(endpoint, body, headers)
+    begin
+      RestClient.post(
+        endpoint, 
+        body.to_json, 
+        headers
+      )
+    rescue Exception => error
+      raise_error(error)
+    end
+  end
+
+  def self.add_query(url, query)
+    (url.include?('?') ? '&' : '?') + query
+  end
+
+  def self.raise_error(error)
+    raise Failure, "#{error.inspect}.  \nSee Adobe Echosign REST API documentation for Error code meanings: https://secure.echosign.com/public/docs/restapi/v2"
+  end
+
+end
+