docusign_rest 0.0.1

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rvmrc
+test.rb
+test/fixtures/vcr/*
+test/docusign_login_config.rb

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in docusign_rest.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jon Kinney
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# DocusignRest
+
+This 'wrapper gem' hooks a Ruby app (currently only tested with Rails) up to the DocuSign REST API to allow for embedded signing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'docusign_rest'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install docusign_rest
+
+## Configuration
+
+There is a bundled rake task that will prompt you for your DocuSign credentials including:
+
+  * Username
+  * Password
+  * Integrator Key
+
+and create the `config/initializers/docusign\_rest.rb` file in your Rails app for you. If the file was unable to be created, the rake task will output the config block for you to manually add to an initializer.
+
+**Note** please run the below task and ensure your initializer is in place before attempting to use any of the methods in this gem. Without the initializer this gem will not be able to properly authenticate you to the DocuSign REST API.
+
+    $ bundle exec rake docusign_rest:generate_config
+
+outputs:
+
+    Please do the following:
+    ------------------------
+    1) Login or register for an account at demo.docusign.net
+        ...or their production url if applicable
+    2) Click 'Preferences' in the upper right corner of the page
+    3) Click 'API' in far lower left corner of the menu
+    4) Request a new 'Integrator Key' via the web interface
+        * You will use this key in one of the next steps to retrieve your 'accountId'
+
+    Please enter your DocuSign username: someone@gmail.com
+    Please enter your DocuSign password: p@ssw0rd1
+    Please enter your DocuSign integrator_key: KEYS-19ddd1cc-cb56-4ca6-87ec-38db47d14b32
+
+    The following block of code was added to config/initializers/docusign_rest.rb
+
+    require 'docusign_rest'
+
+    DocusignRest.configure do |config|
+      config.username       = 'someone@gmail.com'
+      config.password       = 'p@ssw0rd1'
+      config.integrator_key = 'KEYS-19ddd1cc-cb56-4ca6-87ec-38db47d14b32'
+      config.account_id     = '123456'
+    end
+
+## Usage
+
+The docusign\_rest gem makes creating multipart POST (aka file upload) requests to the DocuSign REST API dead simple. It's built on top of Net:HTTP and utilizes the [multipart-post](https://github.com/nicksieger/multipart-post) gem to assist with formatting the multipart requests for the DocuSign REST API. The DocuSign REST API requires that all files be embedded as JSON directly in the request body (not the body\_stream like multipart-post does by default) so the docusign\_rest gem takes care of setting that up for you. 
+
+This gem also monkey patches one small part of multipart-post to inject some header values and formatting that DocuSign requires. If you would like to see the monkey patched code please take a look at [lib/multipart-post/parts.rb](https://github.com/j2fly/docusign_rest/blob/master/lib/multipart_post/parts.rb). It's only re-opening one method, but feel free to make sure you understand that monkey patch if it concerns you. 
+
+### Examples
+
+* These examples assume you have already run the `docusign_rest:generate_config` rake task and have the configure block properly setup in an initializer with your username, password, integrator\_key, and account\_id.
+
+**Getting login information:**
+
+```ruby
+client = DocusignRest::Client.new
+puts client.get_account_id
+```
+
+
+**Creating an envelope from a document:**
+
+```ruby
+client = DocusignRest::Client.new
+response = client.create_envelope_from_document(
+  email: {
+    subject: "test email subject",
+    body: "this is the email body and it's large!"
+  },
+  # If embedded is set to true  in the signers array below, emails
+  # don't go out and you can embed the signature page in an iFrame
+  # by using the get_recipient_view method
+  signers: [
+    {
+      #embedded: true,
+      name: 'Test Guy',
+      email: 'someone@gmail.com'
+    },
+    {
+      #embedded: true,
+      name: 'Test Girl',
+      email: 'someone@gmail.com'
+    }
+  ],
+  files: [
+    {path: 'test.pdf', name: 'test.pdf'},
+    {path: 'test2.pdf', name: 'test2.pdf'}
+  ],
+  status: 'sent'
+)
+response = JSON.parse(response.body)
+response["status"].must_equal "sent"
+```
+
+
+**Creating a template:**
+
+```ruby
+client = DocusignRest::Client.new
+response = client.create_template(
+  description: 'Cool Description',
+  name: "Cool Template Name",
+  signers: [
+    {
+      embedded: true,
+      name: 'jon',
+      email: 'someone@gmail.com',
+      role_name: 'Issuer',
+      anchor_string: 'sign here'
+    }
+  ],
+  files: [
+    {path: 'test.pdf', name: 'test.pdf'}
+  ]
+)
+@template_response = JSON.parse(response.body)
+```
+
+
+**Creating an envelope from a template:**
+
+```ruby
+client = DocusignRest::Client.new
+response = client.create_envelope_from_template(
+  status: 'sent',
+  email: {
+    subject: "The test email subject envelope",
+    body: "Envelope body content here"
+  },
+  template_id: @template_response["templateId"],
+  signers: [
+    {
+      embedded: true,
+      name: 'jon',
+      email: 'someone@gmail.com',
+      role_name: 'Issuer'
+    }
+  ]
+)
+@envelope_response = JSON.parse(response.body)
+```
+
+
+**Retrieving the url for embedded signing**
+
+```ruby
+client = DocusignRest::Client.new
+response = client.get_recipient_view(
+  envelope_id: @envelope_response["envelopeId"],
+  name: 'jon',
+  email: 'someone@gmail.com',
+  return_url: 'http://google.com'
+)
+@view_recipient_response = JSON.parse(response.body)
+puts @view_recipient_response["url"]
+```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`) making sure to write tests to ensure nothing breaks
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+### Running the tests
+
+In order to run the tests you'll need to register for a (free) DocuSign developer account. After doing so you'll have a username, password, and integrator key. Armed with that information execute the following ruby file:
+
+    $ ruby lib/tasks/docusign_task.rb
+
+This calls a rake task which adds a non-version controlled file in the test folder called 'docusign_login_config.rb' which holds your account specific credentials and is required in order to hit the test API through the test suite.
+
+**VCR**
+
+The test suite uses VCR and is configured to record only the first request by using the 'once' configuration option surrounding each API request. If you want to experiment with the API or are getting several errors with the test suite, you may want to change the VCR config record setting to 'all' temporarily which will write a new YAML file for each request each time you hit the API. However, this significantly slow down tests and essentially negates the benefit of VCR which is to mock out the API entirely and keep the tests speedy.

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+Rake::TestTask.new do |test|
+  test.libs << 'lib' << 'test'
+  test.ruby_opts << "-rubygems"
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end

data/docusign_rest.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/docusign_rest/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Jon Kinney"]
+  gem.email         = ["jonkinney@gmail.com"]
+  gem.description   = %q{Hooks a Rails app up to the DocuSign service through the DocuSign REST API}
+  gem.summary       = %q{Use this gem to embed signing of documents in a Rails app through the DocuSign REST API}
+  gem.homepage      = "https://github.com/j2fly/docusign_rest"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "docusign_rest"
+  gem.require_paths = ["lib"]
+  gem.version       = DocusignRest::VERSION
+
+  gem.add_dependency('multipart-post', '>= 1.1.5')
+  gem.add_dependency('json')
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('minitest')
+  gem.add_development_dependency('turn')
+  gem.add_development_dependency('pry')
+  gem.add_development_dependency('vcr')
+  gem.add_development_dependency('fakeweb')
+end

data/example.rb

@@ -0,0 +1,40 @@
+require 'docusign_rest'
+
+DocusignRest.configure do |config|
+  config.username       = "someone@gmail.com"
+  config.password       = "password"
+  config.integrator_key = "KEYS-16dbc1bc-ca56-4ea6-87ec-29db47d94b32"
+  config.account_id     = "123456"
+end
+
+client = DocusignRest::Client.new
+
+response = client.create_envelope_from_document(
+  email: {
+    subject: "test email subject",
+    body: "this is the email body and it's large!"
+  },
+  # If embedded is set to true  in the signers array below, emails
+  # don't go out and you can embed the signature page in an iFrame
+  # by using the get_recipient_view method
+  signers: [
+    {
+      #embedded: true,
+      name: 'Test Guy',
+      email: 'someone@gmail.com'
+    },
+    {
+      #embedded: true,
+      name: 'Test Girl',
+      email: 'someone+else@gmail.com'
+    }
+  ],
+  files: [
+    {path: 'test.pdf', name: 'test.pdf'},
+    {path: 'test2.pdf', name: 'test2.pdf'}
+  ],
+  status: 'sent'
+)
+
+response = JSON.parse(response.body)
+puts response.body

data/lib/docusign_rest.rb

@@ -0,0 +1,14 @@
+require 'docusign_rest/version'
+require 'docusign_rest/configuration'
+require 'docusign_rest/client'
+require 'multipart_post' #require the multipart-post gem itself
+require 'net/http/post/multipart' #require the multipart-post net/http/post/multipart monkey patch
+require 'multipart_post/parts' #require my monkey patched parts.rb which adjusts the build_part method
+require 'net/http'
+require 'json'
+
+module DocusignRest
+  require "docusign_rest/railtie" if defined?(Rails)
+
+  extend Configuration
+end

data/lib/docusign_rest/client.rb

@@ -0,0 +1,609 @@
+module DocusignRest
+
+  class Client
+    # Define the same set of accessors as the DocusignRest module
+    attr_accessor *Configuration::VALID_CONFIG_KEYS
+    attr_accessor :docusign_authentication_headers, :acct_id
+
+    def initialize(options={})
+      # Merge the config values from the module and those passed to the client.
+      merged_options = DocusignRest.options.merge(options)
+
+      # Copy the merged values to this client and ignore those not part
+      # of our configuration
+      Configuration::VALID_CONFIG_KEYS.each do |key|
+        send("#{key}=", merged_options[key])
+      end
+
+      # Set up the DocuSign Authentication headers with the values passed from
+      # our config block
+      @docusign_authentication_headers = {
+        "X-DocuSign-Authentication" => "" \
+          "<DocuSignCredentials>" \
+            "<Username>#{DocusignRest.username}</Username>" \
+            "<Password>#{DocusignRest.password}</Password>" \
+            "<IntegratorKey>#{DocusignRest.integrator_key}</IntegratorKey>" \
+          "</DocuSignCredentials>"
+      }
+
+      # Set the account_id from the configure block if present, but can't call
+      # the instance var @account_id because that'll override the attr_accessor
+      # that is automatically configured for the configure block
+      @acct_id = DocusignRest.account_id
+    end
+
+
+    # Internal: sets the default request headers allowing for user overrides
+    # via options[:headers] from within other requests. Additionally injects
+    # the X-DocuSign-Authentication header to authorize the request.
+    #
+    # Client can pass in header options to any given request:
+    # headers: {"Some-Key" => "some/value", "Another-Key" => "another/value"}
+    #
+    # Then we pass them on to this method to merge them with the other
+    # required headers
+    #
+    # Example:
+    #
+    #   headers(options[:headers])
+    #
+    # Returns a merged hash of headers overriding the default Accept header if
+    # the user passes in a new "Accept" header key and adds any other
+    # user-defined headers along with the X-DocuSign-Authentication headers
+    def headers(user_defined_headers={})
+      default = {
+        "Accept" => "application/json" #this seems to get added automatically, so I can probably remove this
+      }
+
+      default.merge!(user_defined_headers) if user_defined_headers
+
+      @docusign_authentication_headers.merge(default)
+    end
+
+
+    # Internal: builds a URI based on the configurable endpoint, api_version,
+    # and the passed in relative url
+    #
+    # url - a relative url requiring a leading forward slash
+    #
+    # Example:
+    #
+    #   build_uri("/login_information")
+    #
+    # Returns a parsed URI object
+    def build_uri(url)
+      URI.parse("#{DocusignRest.endpoint}/#{DocusignRest.api_version}#{url}")
+    end
+
+
+    # Internal: configures Net:HTTP with some default values that are required
+    # for every request to the DocuSign API
+    #
+    # Returns a configured Net::HTTP object into which a request can be passed
+    def initialize_net_http_ssl(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      http
+    end
+
+
+    # Public: gets info necessary to make additional requests to the DocuSign API
+    #
+    # options - hash of headers if the client wants to override something
+    #
+    # Examples:
+    #
+    #   client = DocusignRest::Client.new
+    #   response = client.login_information
+    #   puts response.body
+    #
+    # Returns:
+    #   accountId - For the username, password, and integrator_key specified
+    #   baseUrl   - The base URL for all future DocuSign requests
+    #   email     - The email used when signing up for DocuSign
+    #   isDefault - # TODO identify what this is
+    #   name      - The account name provided when signing up for DocuSign
+    #   userId    - # TODO determine what this is used for, if anything
+    #   userName  - Full name provided when signing up for DocuSign
+    def get_login_information(options={})
+      uri = build_uri("/login_information")
+      request = Net::HTTP::Get.new(uri.request_uri, headers(options[:headers]))
+      http = initialize_net_http_ssl(uri)
+      http.request(request)
+    end
+
+
+    # Internal: uses the get_login_information method to determine the client's
+    # accountId and then caches that value into an instance variable so we
+    # don't end up hitting the API for login_information more than once per
+    # request.
+    #
+    # This is used by the rake task in lib/tasks/docusign_task.rake to add
+    # the config/initialzers/docusign_rest.rb file with the proper config block
+    # which includes the account_id in it. That way we don't require hitting
+    # the /login_information URI in normal requests
+    #
+    # Returns the accountId string
+    def get_account_id
+      unless @acct_id
+        response = get_login_information.body
+        hashed_response = JSON.parse(response)
+        login_accounts = hashed_response['loginAccounts']
+        @acct_id ||= login_accounts.first['accountId']
+      end
+
+      @acct_id
+    end
+
+    def check_embedded_signer(embedded, email)
+      if embedded && embedded == true
+        "\"clientUserId\" : \"#{email}\","
+      end
+    end
+
+    # Internal: takes in an array of hashes of signers and calculates the
+    # recipientId then concatenates all the hashes with commas
+    #
+    # embedded - Tells DocuSign if this is an embedded signer which determines
+    #            weather or not to deliver emails. Also lets us authenticate
+    #            them when they go to do embedded signing. Behind the scenes
+    #            this is setting the clientUserId value to the signer's email.
+    # name     - The name of the signer
+    # email    - The email of the signer
+    #
+    # Returns a hash of users that need to sign the document
+    def get_signers(signers)
+      doc_signers = []
+      signers.each_with_index do |signer, index|
+        doc_signers << "{
+          #{check_embedded_signer(signer[:embedded], signer[:email])}
+          \"name\"         : \"#{signer[:name]}\",
+          \"email\"        : \"#{signer[:email]}\",
+          \"recipientId\"  : \"#{index+1}\"
+        }"
+      end
+      doc_signers.join(",")
+    end
+
+
+    # Internal: takes in an array of hashes of signers and concatenates all the
+    # hashes with commas
+    #
+    # embedded -  Tells DocuSign if this is an embedded signer which determines
+    #             weather or not to deliver emails. Also lets us authenticate
+    #             them when they go to do embedded signing. Behind the scenes
+    #             this is setting the clientUserId value to the signer's email.
+    # name      - The name of the signer
+    # email     - The email of the signer
+    # role_name - The role name of the signer ('Attorney', 'Client', etc.).
+    #
+    # Returns a hash of users that need to be embedded in the template to
+    # create an envelope
+    def get_template_roles(signers)
+      template_roles = []
+      signers.each_with_index do |signer, index|
+        template_roles << "{
+          #{check_embedded_signer(signer[:embedded], signer[:email])}
+          \"name\"         : \"#{signer[:name]}\",
+          \"email\"        : \"#{signer[:email]}\",
+          \"roleName\"     : \"#{signer[:role_name]}\"
+        }"
+      end
+      template_roles.join(",")
+    end
+
+
+    # Internal: takes an array of hashes of signers required to complete a
+    # document and allows for setting several options. Not all options are
+    # currently dynamic but that's easy to change/add which I (and I'm
+    # sure others) will be doing in the future.
+    #
+    # embedded           - Tells DocuSign if this is an embedded signer which
+    #                      determines weather or not to deliver emails. Also
+    #                      lets us authenticate them when they go to do
+    #                      embedded signing. Behind the scenes this is setting
+    #                      the clientUserId value to the signer's email.
+    # email_notification - Send an email or not
+    # role_name          - The signer's role, like 'Attorney' or 'Client', etc.
+    # template_locked    - Doesn't seem to work/do anything
+    # template_required  - Doesn't seem to work/do anything
+    # email              - The signer's email
+    # name               - The signer's name
+    # anchor_string      - The string of text to anchor the 'sign here' tab to
+    # document_id        - If the doc you want signed isn't the first doc in
+    #                      the files options hash
+    # page_number        - Page number of the sign here tab
+    # x_position         - Distance horizontally from the anchor string for the
+    #                      'sign here' tab to appear. Note: doesn't seem to
+    #                      currently work.
+    # y_position         - Distance vertically from the anchor string for the
+    #                      'sign here' tab to appear. Note: doesn't seem to
+    #                      currently work.
+    # sign_here_tab_text - Instead of 'sign here'. Note: doesn't work
+    # tab_label          - TODO: figure out what this is
+    def get_template_signers(signers)
+      doc_signers = []
+      signers.each_with_index do |signer, index|
+        doc_signers << "{
+          \"accessCode\":\"\",
+          \"addAccessCodeToEmail\":false,
+          #{check_embedded_signer(signer[:embedded], signer[:email])}
+          \"customFields\":null,
+          \"emailNotification\":#{signer[:email_notification] || 'null'},
+          \"idCheckConfigurationName\":null,
+          \"idCheckInformationInput\":null,
+          \"inheritEmailNotificationConfiguration\":false,
+          \"note\":\"\",
+          \"phoneAuthentication\":null,
+          \"recipientAttachments\":null,
+          \"recipientId\":\"#{index+1}\",
+          \"requireIdLookup\":false,
+          \"roleName\":\"#{signer[:role_name]}\",
+          \"routingOrder\":#{index+1},
+          \"socialAuthentications\":null,
+          \"templateAccessCodeRequired\":false,
+          \"templateLocked\":#{signer[:template_locked] || 'false'},
+          \"templateRequired\":#{signer[:template_required] || 'false'},
+          \"email\":\"#{signer[:email]}\",
+          \"name\":\"#{signer[:name]}\",
+          \"autoNavigation\":false,
+          \"defaultRecipient\":false,
+          \"signatureInfo\":null,
+          \"tabs\":{
+            \"approveTabs\":null,
+            \"checkboxTabs\":null,
+            \"companyTabs\":null,
+            \"dateSignedTabs\":null,
+            \"dateTabs\":null,
+            \"declineTabs\":null,
+            \"emailTabs\":null,
+            \"envelopeIdTabs\":null,
+            \"fullNameTabs\":null,
+            \"initialHereTabs\":null,
+            \"listTabs\":null,
+            \"noteTabs\":null,
+            \"numberTabs\":null,
+            \"radioGroupTabs\":null,
+            \"signHereTabs\":[
+              {
+                \"anchorString\":\"#{signer[:anchor_string]}\",
+                \"conditionalParentLabel\":null,
+                \"conditionalParentValue\":null,
+                \"documentId\":\"#{signer[:document_id] || '1'}\",
+                \"pageNumber\":\"#{signer[:page_number] || '1'}\",
+                \"recipientId\":\"#{index+1}\",
+                \"templateLocked\":#{signer[:template_locked] || 'false'},
+                \"templateRequired\":#{signer[:template_required] || 'false'},
+                \"xPosition\":\"#{signer[:x_position] || '0'}\",
+                \"yPosition\":\"#{signer[:y_position] || '0'}\",
+                \"name\":\"#{signer[:sign_here_tab_text] || 'Sign Here'}\",
+                \"optional\":false,
+                \"scaleValue\":1,
+                \"tabLabel\":\"#{signer[:tab_label] || 'Signature 1'}\"
+              }
+            ],
+            \"signerAttachmentTabs\":null,
+            \"ssnTabs\":null,
+            \"textTabs\":null,
+            \"titleTabs\":null,
+            \"zipTabs\":null
+          }
+        }"
+      end
+      doc_signers.join(",")
+    end
+
+
+    # Internal: sets up the file ios array
+    #
+    # files - a hash of file params
+    #
+    # Returns the properly formatted ios used to build the file_params hash
+    def create_file_ios(files)
+      # UploadIO is from the multipart-post gem's lib/composite_io.rb:57
+      # where it has this documentation:
+      #
+      # ********************************************************************
+      # Create an upload IO suitable for including in the params hash of a
+      # Net::HTTP::Post::Multipart.
+      #
+      # Can take two forms. The first accepts a filename and content type, and
+      # opens the file for reading (to be closed by finalizer).
+      #
+      # The second accepts an already-open IO, but also requires a third argument,
+      # the filename from which it was opened (particularly useful/recommended if
+      # uploading directly from a form in a framework, which often save the file to
+      # an arbitrarily named RackMultipart file in /tmp).
+      #
+      # Usage:
+      #
+      #     UploadIO.new("file.txt", "text/plain")
+      #     UploadIO.new(file_io, "text/plain", "file.txt")
+      # ********************************************************************
+      #
+      # There is also a 4th undocumented argument, opts={}, which allows us
+      # to send in not only the Content-Disposition of 'file' as required by
+      # DocuSign, but also the documentId parameter which is required as well
+      #
+      ios = []
+      files.each_with_index do |file, index|
+        ios << UploadIO.new(
+                 file[:io] || file[:path],
+                 file[:content_type] || "application/pdf",
+                 file[:name],
+                 "Content-Disposition" => "file; documentid=#{index+1}"
+               )
+      end
+      ios
+    end
+
+
+    # Internal: sets up the file_params for inclusion in a multipart post request
+    #
+    # ios - An array of UploadIO formatted file objects
+    #
+    # Returns a hash of files params suitable for inclusion in a multipart
+    # post request
+    def create_file_params(ios)
+      # multi-doc uploading capabilities, each doc needs to be it's own param
+      file_params = {}
+      ios.each_with_index do |io,index|
+        file_params.merge!("file#{index+1}" => io)
+      end
+      file_params
+    end
+
+
+    # Internal: takes in an array of hashes of documents and calculates the
+    # documentId then concatenates all the hashes with commas
+    #
+    # Returns a hash of documents that are to be uploaded
+    def get_documents(ios)
+      documents = []
+      ios.each_with_index do |io, index|
+        documents << "{
+          \"documentId\" : \"#{index+1}\",
+          \"name\"       : \"#{io.original_filename}\"
+        }"
+      end
+      documents.join(",")
+    end
+
+
+    # Internal sets up the Net::HTTP request
+    #
+    # uri         - The fully qualified final URI
+    # post_body   - The custom post body including the signers, etc
+    # file_params - Formatted hash of ios to merge into the post body
+    # headers     - Allows for passing in custom headers
+    #
+    # Returns a request object suitable for embedding in a request
+    def initialize_net_http_multipart_post_request(uri, post_body, file_params, headers)
+      # Net::HTTP::Post::Multipart is from the multipart-post gem's lib/multipartable.rb
+      #
+      # path       - The fully qualified URI for the request
+      # params     - A hash of params (including files for uploading and a
+      #              customized request body)
+      # headers={} - The fully merged, final request headers
+      # boundary   - Optional: you can give the request a custom boundary
+      #
+      request = Net::HTTP::Post::Multipart.new(
+        uri.request_uri,
+        {post_body: post_body}.merge(file_params),
+        headers
+      )
+
+      # DocuSign requires that we embed the document data in the body of the
+      # JSON request directly so we need to call ".read" on the multipart-post
+      # provided body_stream in order to serialize all the files into a
+      # compatible JSON string.
+      request.body = request.body_stream.read
+      request
+    end
+
+
+    # Public: creates an envelope from a document directly without a template
+    #
+    # file_io       - Optional: an opened file stream of data (if you don't
+    #                 want to save the file to the file system as an incremental
+    #                 step)
+    # file_path     - Required if you don't provide a file_io stream, this is
+    #                 the local path of the file you wish to upload. Absolute
+    #                 paths recommended.
+    # file_name     - The name you want to give to the file you are uploading
+    # content_type  - (for the request body) application/json is what DocuSign
+    #                 is expecting
+    # email_subject - (Optional) short subject line for the email
+    # email_body    - (Optional) custom text that will be injected into the
+    #                 DocuSign generated email
+    # signers       - A hash of users who should receive the document and need
+    #                 to sign it. More info about the options available for
+    #                 this method are documented above it's method definition.
+    # status        - Options include: 'sent', 'created', 'voided' and determine
+    #                 if the envelope is sent out immediately or stored for
+    #                 sending at a later time
+    # headers       - Allows a client to pass in some
+    #
+    # Returns a response object containing:
+    #   envelopeId     - The envelope's ID
+    #   status         - Sent, created, or voided
+    #   statusDateTime - The date/time the envelope was created
+    #   uri            - The relative envelope uri
+    def create_envelope_from_document(options={})
+      ios = create_file_ios(options[:files])
+      file_params = create_file_params(ios)
+
+      post_body = "{
+        \"emailBlurb\"   : \"#{options[:email][:body] if options[:email]}\",
+        \"emailSubject\" : \"#{options[:email][:subject] if options[:email]}\",
+        \"documents\"    : [#{get_documents(ios)}],
+        \"recipients\"   : {
+          \"signers\" : [#{get_signers(options[:signers])}]
+        },
+        \"status\"       : \"#{options[:status]}\"
+      }
+      "
+
+      uri = build_uri("/accounts/#{@acct_id}/envelopes")
+
+      http = initialize_net_http_ssl(uri)
+
+      request = initialize_net_http_multipart_post_request(
+                  uri, post_body, file_params, headers(options[:headers])
+                )
+
+      # Finally do the Net::HTTP request!
+      http.request(request)
+    end
+
+
+    # Public: allows a template to be dynamically created with several options.
+    #
+    # files         - An array of hashes of file parameters which will be used
+    #                 to create actual files suitable for upload in a multipart
+    #                 request.
+    #
+    #                 Options: io, path, name. The io is optional and would
+    #                 require creating a file_io object to embed as the first
+    #                 argument of any given file hash. See the create_file_ios
+    #                 method definition above for more details.
+    #
+    # email/body    - (Optional) sets the text in the email. Note: the envelope
+    #                 seems to override this, not sure why it needs to be
+    #                 configured here as well. I usually leave it blank.
+    # email/subject - (Optional) sets the text in the email. Note: the envelope
+    #                 seems to override this, not sure why it needs to be
+    #                 configured here as well. I usually leave it blank.
+    # signers       - An array of hashes of signers. See the
+    #                 get_template_signers method definition for options.
+    # description   - The template description
+    # name          - The template name
+    # headers       - Optional hash of headers to merge into the existing
+    #                 required headers for a multipart request.
+    #
+    # Returns a response body containing the template's:
+    #   name - Name given above
+    #   templateId - The auto-generated ID provided by DocuSign
+    #   Uri - the URI where the template is located on the DocuSign servers
+    def create_template(options={})
+      ios = create_file_ios(options[:files])
+      file_params = create_file_params(ios)
+
+      post_body = "{
+        \"emailBlurb\"   : \"#{options[:email][:body] if options[:email]}\",
+        \"emailSubject\" : \"#{options[:email][:subject] if options[:email]}\",
+        \"documents\"    : [#{get_documents(ios)}],
+        \"recipients\"   : {
+          \"signers\"    : [#{get_template_signers(options[:signers])}]
+        },
+        \"envelopeTemplateDefinition\" : {
+          \"description\" : \"#{options[:description]}\",
+          \"name\"        : \"#{options[:name]}\",
+          \"pageCount\"   : 1,
+          \"password\"    : \"\",
+          \"shared\"      : false
+        }
+      }
+      "
+
+      uri = build_uri("/accounts/#{@acct_id}/templates")
+
+      http = initialize_net_http_ssl(uri)
+
+      request = initialize_net_http_multipart_post_request(
+                  uri, post_body, file_params, headers(options[:headers])
+                )
+
+      # Finally do the Net::HTTP request!
+      http.request(request)
+    end
+
+
+    # Public: create an envelope for delivery from a template
+    #
+    # headers        - Optional hash of headers to merge into the existing
+    #                  required headers for a POST request.
+    # status         - Options include: 'sent', 'created', 'voided' and
+    #                  determine if the envelope is sent out immediately or
+    #                  stored for sending at a later time
+    # email/body     - Sets the text in the email body
+    # email/subject  - Sets the text in the email subject line
+    # template_id    - The id of the template upon which we want to base this
+    #                  envelope
+    # template_roles - See the get_template_roles method definition for a list
+    #                  of options to pass. Note: for consistency sake we call
+    #                  this 'signers' and not 'templateRoles' when we build up
+    #                  the request in client code.
+    # headers        - Optional hash of headers to merge into the existing
+    #                  required headers for a multipart request.
+    #
+    # Returns a response body containing the envelope's:
+    #   name - Name given above
+    #   templateId - The auto-generated ID provided by DocuSign
+    #   Uri - the URI where the template is located on the DocuSign servers
+    def create_envelope_from_template(options={})
+      content_type = {'Content-Type' => 'application/json'}
+      content_type.merge(options[:headers]) if options[:headers]
+
+      post_body = "{
+        \"status\"        : \"#{options[:status]}\",
+        \"emailBlurb\"    : \"#{options[:email][:body]}\",
+        \"emailSubject\"  : \"#{options[:email][:subject]}\",
+        \"templateId\"    : \"#{options[:template_id]}\",
+        \"templateRoles\" : [#{get_template_roles(options[:signers])}],
+       }"
+
+      uri = build_uri("/accounts/#{@acct_id}/envelopes")
+
+      http = initialize_net_http_ssl(uri)
+
+      request = Net::HTTP::Post.new(
+                  uri.request_uri,
+                  headers(content_type)
+                )
+      request.body = post_body
+
+      http.request(request)
+    end
+
+
+    # Public returns the URL for embedded signing
+    #
+    # envelope_id - the ID of the envelope you wish to use for embedded signing
+    # name        - the name of the signer
+    # email       - the email of the recipient
+    # return_url  - the URL you want the user to be directed to after he or she
+    #               completes the document signing
+    # headers     - optional hash of headers to merge into the existing
+    #               required headers for a multipart request.
+    #
+    # Returns the URL for embedded signing which needs to be put in an iFrame
+    def get_recipient_view(options={})
+      content_type = {'Content-Type' => 'application/json'}
+      content_type.merge(options[:headers]) if options[:headers]
+
+      post_body = "{
+        \"authenticationMethod\" : \"email\",
+        \"clientUserId\"         : \"#{options[:email]}\",
+        \"email\"                : \"#{options[:email]}\",
+        \"returnUrl\"            : \"#{options[:return_url]}\",
+        \"userName\"             : \"#{options[:name]}\",
+       }"
+
+      uri = build_uri("/accounts/#{@acct_id}/envelopes/#{options[:envelope_id]}/views/recipient")
+
+      http = initialize_net_http_ssl(uri)
+
+      request = Net::HTTP::Post.new(
+                  uri.request_uri,
+                  headers(content_type)
+                )
+      request.body = post_body
+
+      http.request(request)
+    end
+
+  end
+
+end