rightsignature-railstyle 1.1.9

data/lib/rightsignature/errors.rb

@@ -0,0 +1,51 @@
+module RightSignature
+  class ResponseError < Exception
+    attr_reader :response
+
+    # Creates new instance of RightSignature::ResponseError to make API calls
+    # * <b>response</b>: Net::HTTP response or HTTParty response
+    # * <b>message</b>: (Optional) Custom error message
+    #     
+    def initialize(response, message=nil)
+      self.set_backtrace(caller[1..-1]) if self.backtrace.nil?
+      @response = response
+      super((message || @response.message))
+    end
+
+    # returns HTTP Code from response
+    def code
+      @response.code
+    end
+  
+    # Suggestions on how to resolve a certain error 
+    def common_solutions
+      if @response.code.to_i == 406
+        "Check the Content-Type and makes sure it's the correct type (usually application/json or application/xml), ensure url has .xml or .json at the end, check 'Accept' header to allow xml or json ('*/*' for anything)"
+      elsif @response.code.to_i  == 401
+        "Check your credentials and make sure they are correct and not expired"
+      elsif @response.code.to_i  >= 500 && @response.code.to_i  < 600
+        "Check the format of your xml or json"
+      end
+    end
+
+    # Attempts to parse an error message from the response body
+    def detailed_message
+      if @response.is_a? Net::HTTPResponse
+        parsed_response = MultiXml.parse(@response.body)
+
+        parsed_response["error"]["message"] if parsed_response && parsed_response["error"]
+      else
+        if @response.parsed_response.is_a? Hash
+          @response.parsed_response["error"]["message"] if @response.parsed_response["error"]
+        end
+      end
+    end
+    
+
+  end
+
+  class TokenResponseError < ResponseError # :nodoc:
+  end
+  class OAuthResponseError < ResponseError # :nodoc:
+  end
+end

data/lib/rightsignature/helpers/normalizing.rb

@@ -0,0 +1,137 @@
+require 'pry'
+module RightSignature::Helpers #:nodoc:
+  module TagsHelper #:nodoc:
+    class <<self #:nodoc:
+      def array_and_metadata_to_string_array(array_of_tags, hash_of_metadata)
+        array_of_tags ||= []
+        hash_of_metadata ||= {}
+        if !(array_of_tags.is_a?(Array) && hash_of_metadata.is_a?(Hash))
+          return raise ArgumentError, "Objects must be an array and a hash"
+        end
+
+        tags_array =
+          array_of_tags.collect{|t| CGI.escape(t)} +
+          hash_of_metadata.collect{ |k,v|
+            "#{CGI.escape(k.to_s)}:#{CGI.escape(v.to_s)}" if ! v.to_s.strip.empty?
+          }.select{ |t|
+            ! t.to_s.strip.empty?
+          }
+
+        tags_array.join ','
+      end
+
+      def tags_array_from_tags_string tags_string
+        tags_string ||= ""
+
+        if ! tags_string.is_a? String
+          return raise ArgumentError, "Object must be a string"
+        end
+
+        tags_string.split(',')
+          .select{|t| t !~ /:/}
+          .collect{|t| CGI.unescape(t)}
+      end
+
+      def metadata_hash_from_tags_string tags_string
+        tags_string ||= ""
+
+        if ! tags_string.is_a? String
+          return raise ArgumentError, "Object must be a string"
+        end
+
+        Hash[
+          tags_string.split(',')
+            .select{ |t| t =~ /:/}
+            .collect{ |t|
+              md = t.split(':')
+              [CGI.unescape(md[0]), CGI.unescape(md[1])]
+            }
+        ]
+      end
+
+      def mixed_array_to_string_array(array_of_tags)
+        return array_of_tags unless array_of_tags.is_a?(Array)
+
+        tags = []
+        array_of_tags.each_with_index do |tag, idx|
+          if tag.is_a? Hash
+            tags << tag.collect{|k,v| "#{CGI.escape(k.to_s)}:#{CGI.escape(v.to_s)}"}
+          elsif tag.is_a? String
+            tags << CGI.escape(tag.to_s)
+          else
+            raise "Tags should be an array of Strings ('tag_name') or Hashes ({'tag_name' => 'value'})"
+          end
+        end
+
+        tags.join(',')
+      end
+
+      def array_to_xml_hash(tags_array)
+        tags_array.map do |t|
+          if t.is_a? Hash
+            name, value = t.first
+            {:tag => {:name => name.to_s, :value => value.to_s}}
+          else
+            {:tag => {:name => t.to_s}}
+          end
+        end
+      end
+
+    end
+  end
+
+  module RolesHelper #:nodoc:
+    class <<self #:nodoc:
+      # Converts [{"Role_ID" => {:name => "John", :email => "email@example.com"}}] to
+      #   [{:role => {:name => "John", :email => "email@example.com", "@role_id" => "Role_ID"} }]
+      # Tries to guess if it's using Role ID or Role Name
+      def array_to_xml_hash(roles_array)
+        roles_hash_array = []
+        roles_array.each do |role_hash|
+          name, value = role_hash.first
+          raise "Hash '#{role_hash.inspect}' is malformed, should be something like {ROLE_NAME => {:name => \"a\", :email => \"a@a.com\"}}" unless value.is_a? Hash and (name.is_a? String or name.is_a? Symbol)
+          if name.match(/^signer_[A-Z]+$/) || name.match(/^cc_[A-Z]+$/)
+            roles_hash_array << {:role => value.merge({"@role_id" => name.to_s})}
+          else
+            roles_hash_array << {:role => value.merge({"@role_name" => name.to_s})}
+          end
+        end
+
+        roles_hash_array
+      end
+
+    end
+  end
+
+
+  module MergeFieldsHelper #:nodoc:
+    class <<self #:nodoc:
+      # Converts [{"Role Name" => {:name => "John", :email => "email@example.com"}}] to
+      #   [{"role roles_name=\"Role Name\"" => {:role => {:name => "John", :email => "email@example.com"}} }]
+      def array_to_xml_hash(merge_fields_array, use_id=false)
+        merge_fields = []
+        merge_fields_array.each do |merge_field_hash|
+          name, value = merge_field_hash.first
+          if use_id
+            merge_fields << { :merge_field => {:value => value.to_s, "@merge_field_id" => name.to_s}}
+          else
+            merge_fields << { :merge_field => {:value => value.to_s, "@merge_field_name" => name.to_s}}
+          end
+        end
+
+        merge_fields
+      end
+
+    end
+  end
+
+   #:nodoc:
+  def array_to_acceptable_names_hash(acceptable_names)
+    converted_fields = []
+    acceptable_names.each do |name|
+      converted_fields << {:name => name}
+    end
+
+    converted_fields
+  end
+end

data/lib/rightsignature/helpers/refine_hash_to_indifferent_access.rb

@@ -0,0 +1,23 @@
+module RefineHashToIndifferentAccess
+
+  # Turn all hashes into "with indifferent access" hashes
+  refine Hash do
+    regular_indexing = instance_method(:[])
+    define_method(:[]) do |key|
+      if has_key? key.to_sym
+        regular_indexing.bind(self).(key.to_sym)
+      else
+        regular_indexing.bind(self).(key.to_s)
+      end
+    end
+
+    regular_deletion = instance_method(:delete)
+    define_method(:delete) do |key|
+      if has_key? key.to_sym
+        regular_deletion.bind(self).(key.to_sym)
+      else
+        regular_deletion.bind(self).(key.to_s)
+      end
+    end
+  end
+end

data/lib/rightsignature/rails_style.rb

@@ -0,0 +1,89 @@
+using RefineHashToIndifferentAccess
+
+module RightSignature
+  class RailsStyle < Connection
+    def prepackage_and_send guid, roles, options
+      # These conversions are basically from Rails-style structures to XML-style structures
+
+      # Convert hashes to array-of-hashes
+      # {k1: v1, k2: v2} => [{k1: v1}, {k2: v2}]
+
+      options[:merge_fields] = (options.delete(:merge_fields)||{}).collect{|k,v| {k => v}}
+
+      roles = roles.collect{|k,v| {k => v}}
+
+      options[:tags] =
+        (options[:tags]||[]) +
+        (options.delete(:metadata)||{}).collect{|k,v| {k => v} if v && ! v.to_s.strip.empty?}.select{|h| ! h.nil?}
+
+      # TODO: Resolve RS choking on anything a HashWithIndifferentAccess
+      super guid, roles, options
+    end
+
+    #TODO: Copy pasta
+    def template_details guid
+      doc = super(guid)[:template]
+
+      tags_string = doc.delete(:tags)
+      doc[:metadata] = TagsHelper.metadata_hash_from_tags_string tags_string
+      doc[:tags] = TagsHelper.tags_array_from_tags_string tags_string
+
+      # Convert a deeply nested array of objects into a normal hash
+      # Note: Must check if it's a deeply nested hash instead, since that is what occurs
+      #  for single-item XLM "arrays"
+      # {..., recipients: {recipient: [{...},{...}]}} => {..., recipients: {...: {...}, ...:{...}}}
+      tmp = doc[:roles][:role].is_a?(Hash) ? [doc[:roles][:role]] : doc[:roles][:role]
+      doc[:roles] = tmp.reduce({}){|h, v| h[v[:document_role_id]] = v and h}
+
+      tmp = doc[:merge_fields][:merge_field].is_a?(Hash) ? [doc[:merge_fields][:merge_field]] : doc[:merge_fields][:merge_field]
+      doc[:merge_fields] = tmp.reduce({}){|h, v| h[v[:name]] = v and h}
+
+      # Extract a few fields from a deeply nested array
+      tmp = doc[:pages][:page].is_a?(Hash) ? doc[:pages][:page] : doc[:pages][:page].first
+      %i(original_template_guid original_template_filename).each do |sym|
+        doc[sym] = tmp[sym]
+      end
+      doc.delete(:pages)
+
+      %i(thumbnail_url).each do |sym|
+        doc[sym] = CGI.unescape doc[sym]
+      end
+
+      doc
+    end
+
+    def document_details guid
+      doc = super(guid)[:document]
+
+      tags_string = doc.delete(:tags)
+      doc[:metadata] = TagsHelper.metadata_hash_from_tags_string tags_string
+      doc[:tags] = TagsHelper.tags_array_from_tags_string tags_string
+
+      # Convert a deeply nested array of objects into a normal hash
+      # Note: Must check if it's a deeply nested hash instead, since that is what occurs
+      #  for single-item XLM "arrays"
+      # {..., recipients: {recipient: [{...},{...}]}} => {..., recipients: {...: {...}, ...:{...}}}
+      tmp = doc[:recipients][:recipient].is_a?(Hash) ? [doc[:recipients][:recipient]] : doc[:recipients][:recipient]
+      doc[:recipients] = tmp.reduce({}){|h, v| h[v[:role_id]] = v and h}
+
+      tmp = doc[:audit_trails][:audit_trail].is_a?(Hash) ? [doc[:audit_trails][:audit_trail]] : doc[:audit_trails][:audit_trail]
+      doc[:audit_trails] = tmp.reduce({}){|h, v| h[v[:timestamp]] = v and h}
+
+      tmp = doc[:form_fields][:form_field].is_a?(Hash) ? [doc[:form_fields][:form_field]] : doc[:form_fields][:form_field]
+      doc[:form_fields] = tmp.reduce({}){|h, v| h[v[:name]] = v and h}
+
+      # Extract a few fields from a deeply nested array
+      tmp = doc[:pages][:page].is_a?(Hash) ? doc[:pages][:page] : doc[:pages][:page].first
+      %i(original_template_guid original_template_filename).each do |sym|
+        doc[sym] = tmp[sym]
+      end
+      doc.delete(:pages)
+
+      %i(original_url pdf_url thumbnail_url large_url signed_pdf_url).each do |sym|
+        doc[sym] = CGI.unescape doc[sym]
+      end
+
+      doc
+    end
+  end
+end

data/lib/rightsignature/template.rb

@@ -0,0 +1,299 @@
+using RefineHashToIndifferentAccess
+
+module RightSignature
+  module Template
+    include RightSignature::Helpers
+    # List Templates with optional filters
+    # * <b>Options</b>: (optional) Hash of filters to use
+    #   * <b>page</b>: page number
+    #   * <b>per_page</b>: number of templates to return per page.
+    #     API only supports 10, 20, 30, 40, or 50. Default is 10.
+    #   * <b>tags</b>: filter templates by given tags. Array of strings, for name/value tags colon (:) should separate name and value.
+    #     Ex. "single_tag,tag_key:tag_value" would find templates with 'single_tag' and the name/value of 'tag_key' with value 'tag_value'.
+    #   * <b>search</b>: term to search for in templates.
+    #
+    # Ex.
+    #   options = {
+    #     :state => ['completed', 'trashed'],
+    #     :page => 1,
+    #     :per_page => 20,
+    #     :search => "me",
+    #     :tags => ["single_tag", "key" => "with_value"]
+    #   }
+    #   @rs_connection.templates_list(options)
+    def templates_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
+      get "/api/templates.xml", options
+    end
+
+    # Gets template details
+    # * <b>guid</b>: templates guid. Ex. a_1_zcfdidf8fi23
+    def template_details(guid)
+      get "/api/templates/#{guid}.xml", {}
+    end
+
+    # Clones a template so it can be used for sending. Always first step in sending a template.
+    # * <b>guid</b>: templates guid. Ex. a_1_zcfdidf8fi23
+    def prepackage(guid)
+      post "/api/templates/#{guid}/prepackage.xml", {}
+    end
+
+    # Prefills template. Should use a <b>prepackaged</b> template first.
+    # * <b>guid</b>: templates guid. Ex. a_1_zcfdidf8fi23
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>roles</b>: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names.
+    #     Ex. [{"Employee" => {:name => "John Employee", :email => "john@employee.com"}}]
+    #       is equivalent to
+    #         <role role_name="Employee">
+    #           <name>John Employee</name>
+    #           <email>john@employee.com</email>
+    #         </role>
+    # * <b>options</b>: other optional values
+    #   * <b>description</b>: document description that'll appear in the email
+    #   * <b>merge_fields</b>: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.
+    #       Ex. [{"Salary" => "$1,000,000"}]
+    #         is equivalent to
+    #           <merge_field merge_field_name="Salary">
+    #           <value>$1,000,000</value>
+    #           </merge_field>
+    #   * <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"
+    #
+    # Ex. call with all options used
+    #   @rs_connection.prefill(
+    #     "a_1_zcfdidf8fi23",
+    #     "Your Employee Handbook",
+    #     [{"employee" => {:name => "John Employee", :email => "john@employee.com"}}],
+    #     {
+    #       :description => "Please read over the handbook and sign it.",
+    #       :merge_fields => [
+    #         { "Department" => "Fun and games" },
+    #         { "Salary" => "$1,000,000" }
+    #       ],
+    #       :expires_in => 5,
+    #       :tags => [
+    #         {:name => 'sent_from_api'},
+    #         {:name => 'user_id', :value => '32'}
+    #       ],
+    #       :redirect_location => "http://yoursite/redirect",
+    #       :callback_location => "http://yoursite/callback"
+    #     })
+    def prefill(guid, subject, roles, options={})
+      use_merge_field_ids = options.delete(:use_merge_field_ids)
+      xml_hash = {
+        :template => {
+          :guid => guid,
+          :action => "prefill",
+          :subject => subject
+        }.merge(options)
+      }
+
+      xml_hash[:template][:roles] = RolesHelper.array_to_xml_hash(roles)
+
+      # Optional arguments
+      xml_hash[:template][:merge_fields] = MergeFieldsHelper.array_to_xml_hash(options[:merge_fields], use_merge_field_ids) if options[:merge_fields]
+      xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]
+
+      post "/api/templates.xml", xml_hash
+    end
+
+    # Prepackages and sends template.
+    # * <b>guid</b>: templates guid. Ex. a_1_zcfdidf8fi23
+    # * <b>roles</b>: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names.
+    #     Ex. [{"Employee" => {:name => "John Employee", :email => "john@employee.com"}}]
+    #       is equivalent to
+    #         <role role_name="Employee">
+    #           <name>John Employee</name>
+    #           <email>john@employee.com</email>
+    #         </role>
+    # * <b>options</b>: other optional values
+    #   * <b>subject</b>: subject of the document that'll appear in email. Defaults to template's subject
+    #   * <b>description</b>: document description that'll appear in the email
+    #   * <b>merge_fields</b>: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.
+    #       Ex. [{"Salary" => "$1,000,000"}]
+    #         is equivalent to
+    #           <merge_field merge_field_name="Salary">
+    #           <value>$1,000,000</value>
+    #           </merge_field>
+    #   * <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 {:name => 'tag_name'} (for simple tag) or {:name => 'tag_name', :value => 'value'} (for tuples pairs)
+    #       Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "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"
+    #
+    # Ex. call with all options used
+    #   @rs_connection.prepackage_and_send(
+    #     "a_1_zcfdidf8fi23",
+    #     "Your Employee Handbook",
+    #     [{"employee" => {:name => "John Employee", :email => "john@employee.com"}}],
+    #     {
+    #       :description => "Please read over the handbook and sign it.",
+    #       :merge_fields => [
+    #         { "Department" => "Fun and games" },
+    #         { "Salary" => "$1,000,000" }
+    #       ],
+    #       :expires_in => 5,
+    #       :tags => [
+    #         {:name => 'sent_from_api'},
+    #         {:name => 'user_id', :value => '32'}
+    #       ],
+    #       :callback_location => "http://yoursite/callback"
+    #     })
+    def prepackage_and_send(guid, roles, options={})
+      response = prepackage(guid)
+      new_guid = response["template"]["guid"]
+      send_template(new_guid, options.delete(:subject) || response["template"]["subject"], roles, options)
+    end
+
+    # Sends template. Should use a <b>prepackaged</b> template first. Easier to use <b>prepackage_and_send</b> for most cases.
+    # * <b>guid</b>: templates guid. Ex. a_1_zcfdidf8fi23
+    # * <b>subject</b>: subject of the document that'll appear in email
+    # * <b>roles</b>: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names.
+    #     Ex. [{"Employee" => {:name => "John Employee", :email => "john@employee.com"}}]
+    #       is equivalent to
+    #         <role role_name="Employee">
+    #           <name>John Employee</name>
+    #           <email>john@employee.com</email>
+    #         </role>
+    # * <b>options</b>: other optional values
+    #   * <b>description</b>: document description that'll appear in the email
+    #   * <b>merge_fields</b>: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.
+    #       Ex. [{"Salary" => "$1,000,000"}]
+    #         is equivalent to
+    #           <merge_field merge_field_name="Salary">
+    #           <value>$1,000,000</value>
+    #           </merge_field>
+    #   * <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 {:name => 'tag_name'} (for simple tag) or {:name => 'tag_name', :value => 'value'} (for tuples pairs)
+    #       Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "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"
+    #
+    # Ex. call with all options used
+    #   @rs_connection.send_template(
+    #     "a_1_zcfdidf8fi23",
+    #     "Your Employee Handbook",
+    #     [{"employee" => {:name => "John Employee", :email => "john@employee.com"}}],
+    #     {
+    #       :description => "Please read over the handbook and sign it.",
+    #       :merge_fields => [
+    #         { "Department" => "Fun and games" },
+    #         { "Salary" => "$1,000,000" }
+    #       ],
+    #       :expires_in => 5,
+    #       :tags => [
+    #         {:name => 'sent_from_api'},
+    #         {:name => 'user_id', :value => '32'}
+    #       ],
+    #       :callback_location => "http://yoursite/callback"
+    #     })
+    def send_template(guid, subject, roles, options={})
+      prefill(guid, subject, roles, options.merge({:action => 'send'}))
+    end
+
+    # Creates a URL that give person ability to create a template in your account.
+    # * <b>options</b>: optional options for redirected person
+    #   * <b>callback_location</b>: URI encoded URL that specifies the location we will POST a callback notification to when the template has been created.
+    #   * <b>redirect_location</b>: A URI encoded URL that specifies the location we will redirect the user to, after they have created a template.
+    #   * <b>tags</b>: tags to add to the template. an array of 'tag_name' (for simple tag) or {'tag_name' => 'value'} (for tuples pairs)
+    #       Ex. ['created_from_api', {"user_id" => "123"}]
+    #   * <b>acceptable_role_names</b>: The user creating the Template will be forced to select one of the values provided.
+    #       There will be no free-form name entry when adding roles to the Template. An array of strings.
+    #       Ex. ["Employee", "Employeer"]
+    #   * <b>acceptable_merge_field_names</b>: The user creating the Template will be forced to select one of the values provided.
+    #       There will be no free-form name entry when adding merge fields to the Template.
+    #       Ex. ["Location", "Tax ID", "Company Name"]
+    def generate_build_url(options={})
+      xml_hash = {:template => options}
+      xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]
+
+      [:acceptable_merge_field_names, :acceptable_role_names].each do |option|
+        xml_hash[:template][option] = array_to_acceptable_names_hash(options[option]) if options[option]
+      end
+
+      response = post "/api/templates/generate_build_token.xml", xml_hash
+
+      redirect_token = response["token"]["redirect_token"]
+
+      "#{site}/builder/new?rt=#{redirect_token}"
+    end
+
+    # Sends template with all roles as embedded signers and returns an array of hashes with :name and :url for each signer link.
+    # * <b>guid</b>: templates guid. Ex. a_1_zcfdidf8fi23
+    # * <b>roles</b>: Recipients of the document, should be an array of role names in a hash with keys as role_names.
+    #     Ex. [{"Employee" => {:name => "John Employee"}]
+    #       is equivalent to
+    #         <role role_name="Employee">
+    #           <name>John Employee</name>
+    #           <email>noemail@rightsignature.com</email>
+    #         </role>
+    # * <b>options</b>: other optional values
+    #   * <b>subject</b>: subject of the document that'll appear in email. Defaults to Template's subject
+    #   * <b>description</b>: document description that'll appear in the email
+    #   * <b>merge_fields</b>: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.
+    #       Ex. [{"Salary" => "$1,000,000"}]
+    #         is equivalent to
+    #           <merge_field merge_field_name="Salary">
+    #           <value>$1,000,000</value>
+    #           </merge_field>
+    #   * <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 {:name => 'tag_name'} (for simple tag) or {:name => 'tag_name', :value => 'value'} (for tuples pairs)
+    #       Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "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>redirect_location</b>: A URI encoded URL that specifies the location for the signing widget to redirect the user to after it is signed.
+    #       Ex. "http://yoursite/thanks_for_signing"
+    #
+    # Ex. call with all options used
+    #   @rs_connection.send_as_embedded_signers(
+    #     "a_1_zcfdidf8fi23",
+    #     "Your Employee Handbook",
+    #     [{"employee" => {:name => "John Employee", :email => "john@employee.com"}}],
+    #     {
+    #       :description => "Please read over the handbook and sign it.",
+    #       :merge_fields => [
+    #         { "Department" => "Fun and games" },
+    #         { "Salary" => "$1,000,000" }
+    #       ],
+    #       :expires_in => 5,
+    #       :tags => [
+    #         {:name => 'sent_from_api'},
+    #         {:name => 'user_id', :value => '32'}
+    #       ],
+    #       :redirect_location => "http://yoursite/redirect_from_signing"
+    #     })
+    def send_as_embedded_signers(guid, recipients, options={})
+      redirect_location = options.delete(:redirect_location)
+
+      response = prepackage(guid)
+      template = response["template"]
+
+      recipients.each do |role_hash|
+        key, value = role_hash.first
+        role_hash[key][:email] = "noemail@rightsignature.com" unless role_hash[key]["email"] || role_hash[key][:email]
+      end
+
+      response = send_template(template["guid"], options[:subject] || template["subject"], recipients, options)
+      document_guid = response["document"]["guid"]
+
+      get_document_signer_links_for(document_guid, redirect_location)
+    end
+
+    # Deletes a template
+    # * <b>guid</b>: Document GUID
+    #
+    # Ex. Delete template GUID123
+    #   @rs_connection.trash_template("GUID123")
+    #
+    def trash_template(guid)
+      delete "/api/templates/#{guid}.xml"
+    end
+  end
+end