rightsignature-railstyle 1.1.9

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/rightsignature.rb

@@ -0,0 +1,15 @@
+require 'httparty'
+require 'xml-fu'
+require 'oauth'
+require 'rightsignature/errors'
+require 'rightsignature/helpers/normalizing'
+require 'rightsignature/helpers/refine_hash_to_indifferent_access'
+require 'rightsignature/document'
+require 'rightsignature/template'
+require 'rightsignature/account'
+require 'rightsignature/connection/oauth_connection'
+require 'rightsignature/connection/token_connection'
+require 'rightsignature/connection'
+require 'rightsignature/rails_style'
+
+XmlFu.config.symbol_conversion_algorithm = :none

data/lib/rightsignature/account.rb

@@ -0,0 +1,37 @@
+module RightSignature
+  module Account 
+    # Return account information about API user
+    # 
+    # Ex. 
+    #   @rs_connection.user_details
+    # 
+    def user_details
+      get "/api/users/user_details.xml"
+    end
+    
+    # Creates a user on API user's account
+    # * name: User's name
+    # * email: User's email
+    # 
+    # Ex. 
+    #   @rs_connection.add_user("John Bellingham", "john@example.com")
+    # 
+    def add_user(name, email)
+      post "/api/users.xml", {:user => {:name => name, :email => email}}
+    end
+    
+    # Return account's usage report (# of documents sent)
+    # * <b>since</b>: ("month"/"week"/"day") only count documents sent within a certain time
+    # * <b>signed</b>: (true/false) only count signed document
+    # 
+    # Ex. Return count of signed documents sent this month
+    #   @rs_connection.usage_report("month", true)
+    # 
+    def usage_report(since=nil, signed=nil)
+      options = {}
+      options[:since] = since if since && ["month", "week", "day"].include?(since)
+      options[:signed] = signed.to_s unless signed.nil?
+      get "/api/account/usage_report.xml", options
+    end
+  end
+end

data/lib/rightsignature/connection.rb

@@ -0,0 +1,207 @@
+module RightSignature
+  class Connection
+    include RightSignature::Document
+    include RightSignature::Account
+    include RightSignature::Template
+
+    attr_accessor :configuration
+    attr_accessor :oauth_connection
+    attr_accessor :token_connection
+
+    # Creates new instance of RightSignature::Connection to make API calls
+    # * <b>creds</b>: Hash of credentials for API Token or OAuth. If both are specified, it uses API Token
+    #   * Hash key for API Token:
+    #     * :api_token
+    #   * Hash keys for OAuth:
+    #     * :consumer_key
+    #     * :consumer_secret
+    #     * :access_token
+    #     * :access_secret
+    #     
+    # Example for Api Token:
+    #   @rs_connection = RightSignature::Connection.new(:api_token => "MYTOKEN")
+    # 
+    # Example for OAuth:
+    #   @rs_connection = RightSignature::Connection.new(:consumer_key => "ckey", :consumer_secret => "csecret", :access_token => "atoken", :access_secret => "asecret")
+    # 
+    def initialize(creds={})
+      @configuration = {}
+      RightSignature::Connection.oauth_keys.each do |key|
+        @configuration[key] = creds[key].to_s
+      end
+
+      RightSignature::Connection.api_token_keys.each do |key|
+        @configuration[key] = creds[key].to_s
+      end
+
+      @token_connection = RightSignature::TokenConnection.new(*RightSignature::Connection.api_token_keys.map{|k| @configuration[k]})
+      @oauth_connection = RightSignature::OauthConnection.new(@configuration)
+
+      @configuration
+    end
+
+    # Checks if credentials are set for either API Token or for OAuth 
+    # 
+    def check_credentials
+      raise "Please set load_configuration with #{RightSignature::Connection.api_token_keys.join(',')} or #{RightSignature::Connection.oauth_keys.join(',')}" unless has_api_token? || has_oauth_credentials?
+    end
+
+    # Checks if API Token credentials are set. Does not validate creds with server.
+    # 
+    def has_api_token?
+      return false if @configuration.nil?
+      RightSignature::Connection.api_token_keys.each do |key|
+        return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
+      end
+
+      return true
+    end
+
+    # Checks if OAuth credentials are set. Does not validate creds with server.
+    # 
+    def has_oauth_credentials?
+      return false if @configuration.nil?
+      RightSignature::Connection.oauth_keys.each do |key| 
+        return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
+      end
+
+      return true
+    end
+
+    # :nodoc:
+    def self.oauth_keys
+      [:consumer_key, :consumer_secret, :access_token, :access_secret].freeze
+    end
+
+    # :nodoc:
+    def self.api_token_keys
+      [:api_token].freeze
+    end    
+    
+    # :nodoc:
+    def site
+      if has_api_token?
+        RightSignature::TokenConnection.base_uri
+      else
+        @oauth_connection.oauth_consumer.site
+      end
+    end
+
+    # PUT request to server
+    # 
+    # Arguments:
+    #   url: Path of API call
+    #   body: XML body in hash format
+    #   url: Hash of HTTP headers to include
+    # 
+    # Example:
+    #   @rs_connection.put("/api/documents.xml", {:documents=> {}}, {"User-Agent" => "My Own"})
+    # 
+    def put(url, body={}, headers={})
+      if has_api_token?
+        options = {}
+        options[:headers] = headers
+        options[:body] = XmlFu.xml(body)
+        
+        parse_response(@token_connection.request(:put, url, options))
+      else
+        parse_response(@oauth_connection.request(:put, url, XmlFu.xml(body), headers))
+      end
+    end
+
+    # DELETE request to server
+    # 
+    # Arguments:
+    #   url: Path of API call
+    #   url: Hash of HTTP headers to include
+    # 
+    # Example:
+    #   @rs_connection.delete("/api/users.xml", {"User-Agent" => "My Own"})
+    # 
+    def delete(url, headers={})
+      if has_api_token?
+        options = {}
+        options[:headers] = headers
+
+        parse_response(@token_connection.request(:delete, url, options))
+      else
+        parse_response(@oauth_connection.request(:delete, url, headers))
+      end
+    end
+
+    # GET request to server
+    # 
+    # Arguments:
+    #   url: Path of API call
+    #   params: Hash of URL parameters to include in request
+    #   url: Hash of HTTP headers to include
+    # 
+    # Example:
+    #   @rs_connection.get("/api/documents.xml", {:search => "my term"}, {"User-Agent" => "My Own"})
+    # 
+    def get(url, params={}, headers={})
+      check_credentials
+      
+      if has_api_token?
+        options = {}
+        options[:headers] = headers
+        options[:query] = params
+        parse_response(@token_connection.request(:get, url, options))
+      else
+        unless params.empty?
+          url = "#{url}?#{params.sort.map{|param| URI.escape("#{param[0]}=#{param[1]}")}.join('&')}"
+        end
+        parse_response(@oauth_connection.request(:get, url, headers))
+      end
+    end
+
+    # POST request to server
+    # 
+    # Arguments:
+    #   url: Path of API call
+    #   url: Hash of HTTP headers to include
+    # 
+    # Example:
+    #   @rs_connection.post("/api/users.xml", {"User-Agent" => "My Own"})
+    # 
+    def post(url, body={}, headers={})
+      check_credentials
+      
+      if has_api_token?
+        options = {}
+        options[:headers] = headers
+        options[:body] = XmlFu.xml(body)
+        parse_response(@token_connection.request(:post, url, options))
+      else
+        parse_response(@oauth_connection.request(:post, url, XmlFu.xml(body), headers))
+      end
+    end
+    
+    # Attempts to parse response from a connection and return it as a hash. 
+    # If response isn't a success, an RightSignature::ResponseError is raised
+    # 
+    # Arguments:
+    #   url: Path of API call
+    #   url: Hash of HTTP headers to include
+    # 
+    # Example:
+    #   @rs_connection.delete("/api/users.xml", {"User-Agent" => "My Own"})
+    # 
+    def parse_response(response)
+      if response.is_a? Net::HTTPResponse
+        unless response.is_a? Net::HTTPSuccess
+          raise RightSignature::ResponseError.new(response)
+        end
+
+        MultiXml.parse(response.body)
+      else
+        unless response.success?
+          raise RightSignature::ResponseError.new(response)
+        end
+        
+        response.parsed_response
+      end
+    end
+    
+  end
+end

data/lib/rightsignature/connection/oauth_connection.rb

@@ -0,0 +1,109 @@
+module RightSignature
+  class OauthConnection
+    attr_reader :request_token
+    attr_reader :consumer_key, :consumer_secret, :oauth_access_token, :oauth_access_secret
+
+    # Creates new instance of RightSignature::OauthConnection to make API calls
+    # * <b>creds</b>: Hash of credentials for OAuth. 
+    #   * Hash keys for OAuth:
+    #     * :consumer_key
+    #     * :consumer_secret
+    #     * :access_token
+    #     * :access_secret
+    #     
+    # Example:
+    #   @rs_oauth = RightSignature::OauthConnection.new(:consumer_key => "ckey", :consumer_secret => "csecret", :access_token => "atoken", :access_secret => "asecret")
+    # 
+    def initialize(credentials={})
+      @consumer_key = credentials[:consumer_key]
+      @consumer_secret = credentials[:consumer_secret]
+      @oauth_access_token = credentials[:access_token]
+      @oauth_access_secret = credentials[:access_secret]
+    end
+    
+    # Oauth consumer
+    def oauth_consumer
+      check_credentials unless @consumer_key && @consumer_secret
+      @oauth_consumer ||= OAuth::Consumer.new(
+        @consumer_key,
+        @consumer_secret,
+        {
+         :site              => "https://rightsignature.com",
+         :scheme            => :header,
+         :http_method        => :post,
+         :authorize_path    =>'/oauth/authorize', 
+         :access_token_path =>'/oauth/access_token', 
+         :request_token_path=>'/oauth/request_token'
+        }
+      )
+    end
+    
+    # Access token
+    def access_token
+      check_credentials
+      @access_token ||= OAuth::AccessToken.new(oauth_consumer,  @oauth_access_token,  @oauth_access_secret)
+    end
+
+    # Replaces access token 
+    # * <b>access_token</b>: access token key
+    # * <b>access_secret</b>: access token secret
+    # 
+    def set_access_token(access_token, access_secret)
+      @oauth_access_token = access_token
+      @oauth_access_secret = access_secret
+      @access_token = OAuth::AccessToken.new(oauth_consumer, @oauth_access_token, @oauth_access_secret)
+    end
+    
+    # Uses consumer to generate a request token.
+    # * <b>o</b>: options hash. Use this to set the :oauth_callback
+    def new_request_token(o = {})
+      @request_token = oauth_consumer.get_request_token(o)
+    end
+
+    # Sets request token.
+    # * <b>request_token</b>: request token key
+    # * <b>request_token_secret</b>: request token secret
+    # 
+    def set_request_token(request_token, request_token_secret)
+      @request_token = OAuth::RequestToken.new(oauth_consumer, request_token, request_token_secret)
+    end
+    
+    # Uses request token and given OAuth verifier to generate an access token. Requires a request token to be set.
+    # * <b>oauth_verifier</b>: OAuth verifier
+    # 
+    def generate_access_token(oauth_verifier)
+      raise "Please set request token with new_request_token" unless @request_token
+      @access_token = @request_token.get_access_token(:oauth_verifier =>  oauth_verifier)
+      @oauth_access_token = @access_token.token
+      @oauth_access_secret = @access_token.secret
+      @access_token
+    end
+    
+    # Generates HTTP request with oauth credentials. Require access_token to be set.
+    # * <b>method</b>: HTTP Method. Ex. ('get'/'post'/'delete'/'put')
+    # * <b>options</b>: OAuth::AccessToken options to pass. Last option should be headers
+    # 
+    def request(method, *options)
+      options.last ||= {}
+      options.last["Accept"] ||= "*/*"
+      options.last["content-type"] ||= "application/xml"
+
+      self.access_token.__send__(method, *options)
+    end
+    
+  private
+    # Raises exception if OAuth credentials are not set.
+    def check_credentials
+      raise "Please set #{RightSignature::Connection.oauth_keys.join(', ')}" unless has_oauth_credentials?
+    end
+
+    # Checks if OAuth credentials are set.
+    def has_oauth_credentials?
+      [@consumer_key, @consumer_secret, @oauth_access_token, @oauth_access_secret].each do |cred| 
+        return false if cred.nil? || cred.match(/^\s*$/)
+      end
+
+      true
+    end
+  end
+end

data/lib/rightsignature/connection/token_connection.rb

@@ -0,0 +1,36 @@
+module RightSignature
+  class TokenConnection
+    include HTTParty
+    base_uri 'https://rightsignature.com'
+    format :xml
+    
+    attr_reader :api_token
+
+    # Creates new instance of RightSignature::TokenConnection to make API calls
+    # * <b>api_token</b>: API Token. 
+    #     
+    # Example:
+    #   @rs_token = RightSignature::TokenConnection.new("APITOKEN")
+    # 
+    def initialize(api_token)
+      @api_token = api_token
+    end
+    
+    # Generates HTTP request with token credentials. Require api_token to be set.
+    # * <b>method</b>: HTTP Method. Ex. ('get'/'post'/'delete'/'put')
+    # * <b>url</b>: request path/url of request
+    # * <b>options</b>: HTTPary options to pass. Last option should be headers
+    # 
+    def request(method, url, options)
+      raise "Please set api_token" if @api_token.nil? || @api_token.empty?
+      
+      options[:headers] ||= {}
+      options[:headers]['api-token'] = @api_token
+      options[:headers]["Accept"] ||= "*/*"
+      options[:headers]["content-type"] ||= "application/xml"
+      self.class.__send__(method, url, options)
+    end
+    
+  end
+
+end

data/lib/rightsignature/document.rb

@@ -0,0 +1,333 @@
+using RefineHashToIndifferentAccess
+
+module RightSignature
+  module Document
+    include RightSignature::Helpers
+
+    # Lists documents
+    #   * <b>options</b>: (optional) search filters
+    #     * <b>:state</b> - (completed/trashed/pending) filter by state
+    #     * <b>:page</b> - page offset
+    #     * <b>:per_page</b> - # of entries per page to return
+    #     * <b>:search</b> - search term filter
+    #     * <b>:tags</b> - tags filter. Array of ["single_tag", {"tag_key" => "tag_value"}]
+    #     * <b>:sort</> - sort documents by given attribute.
+    #     API supports 'created', 'completed', and 'activity'
+    #     * <b>:range</b> - ('today'/'thisweek'/'thismonth'/'alltime'/Date) return documents with a certain date range.
+    #     * <b> :recipient_email</b> - filter document where it has a recipient with given email and involves the current OAuth user.
+    #     * <b> :account</b> - (true/false) include all documents in current account if true.
+    #
+    # Ex.
+    #   options = {
+    #     :state => ['completed', 'trashed'],
+    #     :page => 1,
+    #     :per_page => 20,
+    #     :search => "me",
+    #     :tags => ["single_tag", "key" => "with_value"]
+    #   }
+    #
+    #   @rs_connection.documents_list(options)
+    #
+    def documents_list(options={})
+      if options[:metadata]
+        options[:tags] = TagsHelper.array_and_metadata_to_string_array(options[:tags], options.delete(:metadata))
+      elsif options[:tags]
+        options[:tags] = TagsHelper.mixed_array_to_string_array(options[:tags])
+      end
+      options[:state] = options[:state].join(',') if options[:state] && options[:state].is_a?(Array)
+      get "/api/documents.xml", options
+    end
+
+    # Gets details for a document
+    # * <b>guids</b>: Array of document GUIDs
+    #
+    # Ex. Get details for document GUID123
+    #   @rs_connection.document_details("GUID123")
+    #
+    def document_details(guid)
+      get "/api/documents/#{guid}.xml"
+    end
+
+    # Gets details for multiple documents.
+    # * <b>guids</b>: Array of document GUIDs
+    #
+    # Ex. Get details for documents GUID123 and GUID345
+    #   @rs_connection.documents_batch_details(["GUID123","GUID345"])
+    #
+    def documents_batch_details(guids)
+      get "/api/documents/#{guids.join(',')}/batch_details.xml"
+    end
+
+    # Sends a reminder for a document
+    # * <b>guid</b>: Document GUID
+    #
+    # Ex. Sends reminder for document GUID123
+    #   @rs_connection.send_reminder("GUID123")
+    #
+    def send_reminder(guid)
+      post "/api/documents/#{guid}/send_reminders.xml", {}
+    end
+
+    # Extends a document's expiration date by 7 days
+    # * <b>guid</b>: Document GUID
+    #
+    # Ex. Extend expiration for document GUID123 by 7 days
+    #   @rs_connection.trash_document("GUID123")
+    #
+    def trash_document(guid)
+      post "/api/documents/#{guid}/trash.xml", {}
+    end
+
+
+    # Extends a document's expiration date by 7 days
+    # * <b>guid</b>: Document GUID
+    #
+    # Ex. Extend expiration for document GUID123 by 7 days
+    #   @rs_connection.extend_document_expiration("GUID123")
+    #
+    def extend_document_expiration(guid)
+      post "/api/documents/#{guid}/extend_expiration.xml", {}
+    end
+
+    # <b>REPLACE</b> the tags on a document
+    # tags are an array of 'tag_name' or {'tag_name' => 'value'}
+    #
+    # Ex. Replaces document GUID123 with tags "single_tag", "hello:bye"
+    #   @rs_connection.update_document_tags("GUID123", ["single_tag", {"hello" => "bye"}])
+    def update_document_tags(guid, tags)
+      post "/api/documents/#{guid}/update_tags.xml", { :tags => TagsHelper.array_to_xml_hash(tags) }
+    end
+
+    # Creates a document from a raw data
+    # * <b>file</b>: file binary. Ex. File.read('myfile.pdf')
+    # * <b>filename</b>: original filename
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>recipients</b>: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer').
+    #   One of the recipients requires <b>:is_sender</b> (true/false) to reference the API User and won't need to supply :name and :email
+    #   Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+    #     [
+    #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #       {'is_sender' => true, :role => 'signer'},
+    #     ]
+    # * <b>options</b>: other optional values
+    #   - <b>description</b>: document description that'll appear in the email
+    #   - <b>action</b>: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+    #   - <b>expires_in</b>: number of days before expiring the document. API only allows 2,5,15, or 30.
+    #   - <b>tags</b>: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+    #     Ex. ['sent_from_api', {"user_id" => "32"}]
+    #   - <b>callback_location</b>: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.
+    #     Ex. "http://yoursite/callback"
+    #   - <b>use_text_tags</b>: Document has special Text Tags that RightSignature parse. true or false.
+    #     More info: https://rightsignature.com/apidocs/text_tags
+    def send_document_from_data(file_data, filename, subject, recipients, options={})
+      send_document(subject, recipients, {:type => "base64", :filename => filename, :value => Base64::encode64(file_data)}, options)
+    end
+
+    # Creates a document from a File or path to file
+    # * <b>file</b>: Path to file or File object
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>recipients</b>: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer').
+    #   One of the recipients requires <b>:is_sender</b> (true/false) to reference the API User and won't need to supply :name and :email
+    #   Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+    #     [
+    #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #       {'is_sender' => true, :role => 'signer'},
+    #     ]
+    # * <b>options</b>: other optional values
+    #   - <b>description</b>: document description that'll appear in the email
+    #   - <b>action</b>: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+    #   - <b>expires_in</b>: number of days before expiring the document. API only allows 2,5,15, or 30.
+    #   - <b>tags</b>: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+    #       Ex. ['sent_from_api', {"user_id" => "32"}]
+    #   - <b>callback_location</b>: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.
+    #       Ex. "http://yoursite/callback"
+    #   - <b>use_text_tags</b>: Document has special Text Tags that RightSignature parse. true or false.
+    #       More info: https://rightsignature.com/apidocs/text_tags
+    #
+    # Example:
+    #   recipients = [
+    #     {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #     {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #     {'is_sender' => true, :role => 'signer'}
+    #   ]
+    #   options={
+    #     :tags => [{:tag => {:name => 'sent_from_api'}}, {:tag => {:name => 'user_id', :value => '12345'}}],
+    #     :expires_in => '5 days',
+    #     :action => "redirect",
+    #     'callback_location' => "http://example.com/doc_callback",
+    #     'use_text_tags' => false
+    #   }
+    #   @rs_connection.send_document_from_file("here/is/myfile.pdf", 'My Subject', recipients, options)
+    #
+    def send_document_from_file(file, subject, recipients, options={})
+      send_document(subject, recipients, {:type => "base64", :filename => File.basename(file), :value => Base64::encode64(File.read(file)) }, options)
+    end
+
+    # Creates a document from URL
+    # * <b>url</b>: URL to file
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>recipients</b>: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer').
+    #   One of the recipients requires <b>:is_sender</b> (true/false) to reference the API User and won't need to supply :name and :email
+    #   Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+    #     [
+    #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #       {'is_sender' => true, :role => 'signer'},
+    #     ]
+    # * <b>options</b>: other optional values
+    #   - <b>description</b>: document description that'll appear in the email
+    #   - <b>action</b>: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+    #   - <b>expires_in</b>: number of days before expiring the document. API only allows 2,5,15, or 30.
+    #   - <b>tags</b>: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+    #       Ex. ['sent_from_api', {"user_id" => "32"}]
+    #   - <b>callback_location</b>: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.
+    #       Ex. "http://yoursite/callback"
+    #   - <b>use_text_tags</b>: Document has special Text Tags that RightSignature parse. true or false.
+    #       More info: https://rightsignature.com/apidocs/text_tags
+    #
+    # Example:
+    #   recipients = [
+    #     {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #     {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #     {'is_sender' => true, :role => 'signer'}
+    #   ]
+    #   options={
+    #     :tags => [{:tag => {:name => 'sent_from_api'}}, {:tag => {:name => 'user_id', :value => '12345'}}],
+    #     :expires_in => '5 days',
+    #     :action => "redirect",
+    #     'callback_location' => "http://example.com/doc_callback",
+    #     'use_text_tags' => false
+    #   }
+    #   @rs_connection.send_document_from_url("http://myfile/here", 'My Subject', recipients, options)
+    #
+    def send_document_from_url(url, subject, recipients, options={})
+      send_document(subject, recipients, {:type => "url", :filename => File.basename(url), :value => url }, options)
+    end
+
+    # Creates a document from a base64 encoded file or publicly available URL
+    # * <b>document_data</b>: hash of document source :type ('base64' or 'url'), :filename to be used, :value of source (url or base64 encoded binary)
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>recipients</b>: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer').
+    #   One of the recipients requires <b>:is_sender</b> (true/false) to reference the API User and won't need to supply :name and :email
+    #   Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+    #     [
+    #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #       {'is_sender' => true, :role => 'signer'},
+    #     ]
+    # * options: other optional values
+    #   - <b>description</b>: document description that'll appear in the email
+    #   - <b>action</b>: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+    #   - <b>expires_in</b>: number of days before expiring the document. API only allows 2,5,15, or 30.
+    #   - <b>tags</b>: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+    #       Ex. ['sent_from_api', {"user_id" => "32"}]
+    #   - <b>callback_location</b>: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.
+    #       Ex. "http://yoursite/callback"
+    #   - <b>use_text_tags</b>: Document has special Text Tags that RightSignature parse. true or false.
+    #       More info: https://rightsignature.com/apidocs/text_tags
+    # Ex.
+    #   recipients = [
+    #     {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #     {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #     {'is_sender' => true, :role => 'signer'},
+    #   ]
+    #   document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
+    #   options = {
+    #     :tags => ['sent_from_api', 'user_id' => '12345'],
+    #     :expires_in => '5 days',
+    #     :action => "redirect",
+    #     'callback_location' => "http://example.com/doc_callback",
+    #     'use_text_tags' => false
+    #   }
+    #   @rs_connection.send_document( "My Subject", recipients, document_data, options)
+    #
+    def send_document(subject, recipients, document_data, options={})
+      document_hash = {:document => {
+        :subject => subject,
+        :action => "send",
+        :document_data => document_data
+      }}
+
+      document_hash[:document][:recipients] = []
+      recipients.each do |recipient_hash|
+        document_hash[:document][:recipients] << { :recipient => recipient_hash}
+      end
+
+      document_hash[:document].merge!(options)
+      post "/api/documents.xml", document_hash
+    end
+
+    # Prefills a document from a base64 encoded file or publicly available URL and returns a url that allows someone to send as the API User
+    # * <b>document_data</b>: hash of document source :type ('base64' or 'url'), :filename to be used, :value of source (url or base64 encoded binary)
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>recipients</b>: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer').
+    #   One of the recipients requires <b>:is_sender</b> (true/false) to reference the API User and won't need to supply :name and :email
+    #   Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+    #     [
+    #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #       {'is_sender' => true, :role => 'signer'},
+    #     ]
+    # * <b>options</b>: other optional values
+    #   - <b>description</b>: document description that'll appear in the email
+    #   - <b>action</b>: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+    #   - <b>expires_in</b>: number of days before expiring the document. API only allows 2,5,15, or 30.
+    #   - <b>tags</b>: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+    #     Ex. ['sent_from_api', {"user_id" => "32"}]
+    #   - <b>callback_location</b>: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.
+    #     Ex. "http://yoursite/callback"
+    #   - <b>use_text_tags</b>: Document has special Text Tags that RightSignature parse. true or false.
+    #     More info: https://rightsignature.com/apidocs/text_tags
+    # Ex.
+    #   recipients = [
+    #     {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+    #     {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+    #     {'is_sender' => true, :role => 'signer'},
+    #   ]
+    #   document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
+    #   options = {
+    #     :tags => ['sent_from_api', 'user_id' => '12345'],
+    #     :expires_in => '5 days',
+    #     :action => "redirect",
+    #     'callback_location' => "http://example.com/doc_callback",
+    #     'use_text_tags' => false
+    #   }
+    #   @rs_connection.generate_document_redirect_url( "My Subject", recipients, document_data, options)
+    #
+    def generate_document_redirect_url(subject, recipients, document_data, options={})
+      options[:action] = "redirect"
+      response = send_document(subject, recipients, document_data, options)
+
+      "#{site}/builder/new?rt=#{response['document']['redirect_token']}"
+    end
+
+    # Generates signer links for a Document with signers with email of "noemail@rightsignature.com"
+    # * <b>guid</b>: Document GUID
+    # * <b>redirect_location</b>: (Optional) URL to redirect each signer after it is completed
+    #
+    # Ex. Generate signer links for document GUID123 that redirects users to http://mysite/done_signing after signing
+    #   @rs_connection.get_document_signer_links_for("GUID123", "http://mysite/done_signing")
+    #
+    # Note that ONLY recipients with an email of "noemail@rightsignature.com" will have a signer link
+    def get_document_signer_links_for(guid, redirect_location = nil)
+      params = {}
+      params[:redirect_location] = URI.encode(redirect_location) if redirect_location
+      response = get "/api/documents/#{guid}/signer_links.xml", params
+
+      signer_links = []
+
+      if response["document"]["signer_links"] && response["document"]["signer_links"]["signer_link"].is_a?(Array)
+        response["document"]["signer_links"]["signer_link"].each do |signer_link|
+          signer_links << {"name" => signer_link["name"], "url" => "#{site}/signatures/embedded?rt=#{signer_link["signer_token"]}"}
+        end
+      elsif response["document"]["signer_links"]
+        signer_link = response["document"]["signer_links"]["signer_link"]
+        signer_links << {"name" => signer_link["name"], "url" => "#{site}/signatures/embedded?rt=#{signer_link["signer_token"]}"}
+      end
+      signer_links
+    end
+
+  end
+end