docusigner 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+.bundle/
+*.swp

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+gemspec
+gem 'rake'

data/README.md

@@ -0,0 +1,107 @@
+# Docusigner
+
+This gem is meant to be a simple ActiveResource based interface to DocuSign's REST api.  Where applicable, objects know about their association relationships.
+
+You can read more about DocuSign's REST API:
+
+* [Developer Center](http://www.docusign.com/developers-center)
+* [API Documentation (PDF)](http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf)
+
+*SPECIAL NOTE*: I do not yet have access to the production server, so please consider this a beta.  It has only been tested against the demo server and against the expected responses provided by the above API guide.
+
+
+## Requirements
+
+* `reactive_resource`
+* `multipart_post`
+
+This library will handle multipart post requests to DocuSign and provide the correct headers for the individual posts.  The `multipart_post` gem is required for its internals, but not used as it did not allow the headers DocuSign expects. 
+
+## Setup
+
+You can use either the X-DocuSign-Authentication header or an OAuth2 bearer token to access the API.  Configuration for your app is simple.
+
+### X-DocuSign-Authentication
+
+    Docusigner::Base.authentication = {
+    	:username => "your_username_here",
+    	:password => "your_password_here",
+    	:integrator_key => "your_integrator_key_here"
+    }
+    
+### OAuth2
+
+    Docusigner::Base.token = "your_api_token"
+    
+Additionally, you can easily request (or revoke) a token through the API.
+
+	# request an OAuth2 token
+	token = Docusigner::Oauth2.token("username", "password", "integrator_key")
+	
+	# revoke an OAuth2 token
+	Docusigner::Oauth2.revoke("token")
+	
+### Domain
+
+By default, the API points to the development platform at https://demo.docusign.net.  Changing to the live site is simple:
+
+	Docusigner::Base.site = "https://www.docusign.net/restapi/v2"
+	
+## Usage
+
+Once you've configured the client, accessing resources is easy.  This client is based off of [reactive_resource](http://github.com/justinweiss/reactive_resource) which is built off of [active_resource](http://api.rubyonrails.org/classes/ActiveResource/Base.html).  Code should look similar to using ActiveRecord objects.
+
+### Examples:
+
+#### Fetch basic account information
+
+	# find the account
+	account = Docusigner::Account.find(1234)
+	
+	# access basic attributes
+	account.id
+	=> 1234
+	account.name
+	=> "My account name" 
+
+	# list templates
+	account.templates
+	=> [#<Docusigner::Template>, #<Docusigner::Template>]
+
+#### Create an envelope
+
+	envelope = Docusigner::Envelope.new({
+	  :account_id => 1234,
+	  :emailSubject => "Fee Agreement",
+      :emailBlurb => "Please sign the attached document"
+      :recipients => {
+        :signers => [
+          {
+            :email => "signer@gmail.com",
+            :name => "Bob Smith",
+            :recipientId => 1,
+            :clientUserId => 123, # if you want to do 
+            :tabs => {
+            	# can add tabs here
+            },
+		  }
+        ]
+      },
+      :documents => [
+        {
+          :name => "Fee Agreement",
+          :documentId => 333,
+        }
+      ],
+      :status => Docusigner::Envelope::Status::SENT
+	})
+	envelope.add_document(File.open("/path/to/document.pdf"), 333)
+	envelope.save
+	
+For the most part, the complex data structures expected as parameters can be expressed with nested hashes when creating elements.
+
+## Contributing
+
+If you would like to contribute, please fork my [repository](http://github.com/chingor13/docusigner) and send me a pull request.  Please include tests.
+
+I have not implemented every API endpoint, as I do not have enough time right now.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+require 'rake/testtask'
+require 'rdoc/task'
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+task :build => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+end

data/docusigner.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name = "docusigner"
+  s.version = "0.0.1"
+  s.description = "Unofficial gem for accessing the DocuSign REST API"
+  s.summary = "Unofficial gem for accessing the DocuSign REST API"
+  s.add_dependency "reactive_resource", ">= 0.7.2"
+  s.add_dependency "multipart-post"
+
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency "webmock"
+
+  s.author = "Jeff Ching"
+  s.email = "jeff@chingr.com"
+  s.homepage = "http://github.com/chingor13/docusigner"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+end

data/lib/docusigner/account.rb

@@ -0,0 +1,27 @@
+module Docusigner
+  class Account < Docusigner::Base
+    attr_accessor :id
+
+    has_one :billing_plan
+    has_one :settings, :class_name => "Docusigner::Settings"
+
+    has_many :brands
+    has_many :custom_fields
+
+    # define this manually because the index action requires a from_date
+    def envelopes(from_date, options = {})
+      Docusigner::Envelope.find(:all, :params => options.reverse_merge({:account_id => id, :from_date => from_date}))
+    end
+
+    has_many :folders
+    has_many :groups
+    has_many :templates
+    has_many :users
+
+    def self.find_single(id, options)
+      super(id, options).tap do |r|
+        r.id = id
+      end
+    end
+  end
+end

data/lib/docusigner/base.rb

@@ -0,0 +1,93 @@
+require 'reactive_resource'
+require 'docusigner/multipart'
+module Docusigner
+  class Base < ReactiveResource::Base
+    self.site = "https://demo.docusign.net/restapi/v2"
+    self.format = :json
+    self.include_root_in_json = false
+
+    # allow you to attach documents
+    include Docusigner::Multipart::Resource
+
+    class << self
+      # we want to inherit headers for authentication
+      def headers
+        @headers ||= begin
+          superclass.respond_to?(:headers) ? superclass.headers.dup : {}
+        end
+      end
+
+      def connection(refresh = false)
+        if defined?(@connection) || self == Docusigner::Base
+          @connection = Docusigner::Connection.new(site, format) if refresh || @connection.nil? || !@connection.is_a?(Docusigner::Connection)
+          @connection.timeout = timeout if timeout
+          @connection.ssl_options = ssl_options if ssl_options
+          @connection
+        else
+          superclass.connection
+        end
+      end
+
+      def token=(token)
+        headers['Authorization'] = "Bearer #{token}"
+      end
+
+      def authorization=(options = {})
+        headers['X-DocuSign-Authentication'] = "<DocuSignCredentials><Username>%{username}</Username><Password>%{password}</Password><IntegratorKey>%{integrator_key}</IntegratorKey></DocuSignCredentials>" % options
+      end
+
+      private
+
+      # we want to automatically set the foreign keys if they are provided
+      def instantiate_record(record, prefix_options = {})
+        super(record, prefix_options).tap do |r|
+          prefix_options.each do |k, v|
+            if r.respond_to?("#{k}=")
+              r.send("#{k}=", v)
+            end
+          end
+        end
+      end
+
+      # some of DocuSign's responses contain metadata about the response (e.g. number of records returned)
+      def instantiate_collection(data, prefix_options = {})
+        if data.is_a?(Hash)
+          # if the data has the collection name as a root element, use that to build the records
+          if data.has_key?(collection_name)
+            super(data[collection_name], prefix_options) 
+          else
+            instantiate_flattened_collection(data, prefix_options)
+          end
+        else
+          super(data, prefix_options)
+        end
+      end
+
+      def instantiate_flattened_collection(data, prefix_options)
+        flattened = []
+        data.each do |type, array|
+          array.each do |obj|
+            flattened << instantiate_record(obj.merge(:type => type), prefix_options)
+          end if array.is_a?(Array)
+        end
+        flattened
+      end
+    end
+
+    # the json should skip the root element
+    def to_json(opts = {})
+      as_json.to_json
+    end
+
+    protected
+
+    # we want any generated resources for generated models to extend from this base class
+    #   mainly because we don't want the include the root in the json representation
+    def create_resource_for(resource_name)
+      resource = self.class.const_set(resource_name, Class.new(Docusigner::Base))
+      resource.prefix = self.class.prefix
+      resource.site = self.class.site
+      resource
+    end
+  end
+end

data/lib/docusigner/billing_plan.rb

@@ -0,0 +1,8 @@
+module Docusigner
+  class BillingPlan < Docusigner::Base
+    singleton
+
+    belongs_to :account
+  end
+end
+

data/lib/docusigner/brand.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class Brand < Docusigner::Base
+    belongs_to :account
+  end
+end

data/lib/docusigner/connection.rb

@@ -0,0 +1,24 @@
+module Docusigner
+  class Connection < ActiveResource::Connection
+    def post(path, body = '', headers = {})
+      if body.is_a?(Array)
+        with_auth do
+          req = Docusigner::Multipart::Post.new(path, body, build_request_headers(headers, :post, self.site.merge(path)))
+          handle_response(http.request(req))
+        end
+      else
+        super(path, body, headers)
+      end
+    end
+
+    def put(path, body = '', headers = {})
+      if body.is_a?(Array)
+        req = Docusigner::Multipart::Put.new(path, body, headers)
+        with_auth { request(:request, req, build_request_headers(headers, :put, self.site.merge(path))) }
+      else
+        super(path, body, headers)
+      end
+    end
+  end
+end
+

data/lib/docusigner/custom_field.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class CustomField < Docusigner::Base
+    belongs_to :account
+  end
+end

data/lib/docusigner/document.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class Document < Docusigner::Base
+    belongs_to :envelope
+  end
+end

data/lib/docusigner/envelope.rb

@@ -0,0 +1,55 @@
+module Docusigner
+  class Envelope < Docusigner::Base
+    module Status
+      CREATED   = "created"
+      DELETED   = "deleted"
+      SENT      = "sent"
+      DELIVERED = "delivered"
+      SIGNED    = "signed"
+      COMPLETED = "completed"
+      DECLINED  = "declined"
+      VOIDED    = "voided"
+      TIMED_OUT = "timedout"
+      AUTHORITATIVE_COPY  = "authoritativecopy"
+      TRANSFER_COMPLETED  = "transfercompleted"
+      TEMPLATE  = "template"
+      CORRECT   = "correct"
+    end
+
+    belongs_to :account
+
+    has_many :documents
+    has_many :recipients
+
+    def id
+      attributes["envelopeId"]
+    end
+
+    def send!
+      update_attribute(:status, Docusigner::Envelope::Status::SENT)
+    end
+
+    def void!(reason)
+      update_attributes({
+        :status => Docusigner::Envelope::Status::VOIDED,
+        :voidReason => reason
+      })
+    end
+
+    def recipient_url(params = {})
+      resp = post("views/recipient", prefix_options, params.to_json)
+      self.class.format.decode(resp.body)
+    end
+
+    def sender_url(params = {})
+      resp = post("views/sender", prefix_options, params.to_json)
+      self.class.format.decode(resp.body)
+    end
+
+    def correct_url(params = {})
+      resp = post("views/correct", prefix_options, params.to_json)
+      self.class.format.decode(resp.body)
+    end
+
+  end
+end

data/lib/docusigner/folder.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class Folder < Docusigner::Base
+    belongs_to :account
+  end
+end

data/lib/docusigner/group.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class Group < Docusigner::Base
+    belongs_to :account
+  end
+end

data/lib/docusigner/login_information.rb

@@ -0,0 +1,16 @@
+module Docusigner
+  class LoginInformation < Docusigner::Base
+    singleton
+
+    class << self
+      def change_password(email, current_password, new_password, options = {})
+        body = {
+          "currentPassword" => current_password,
+          "email" => email,
+          "newPassword" => new_password
+        }.merge(options).to_json
+        resp = put(:password, {}, body)
+      end
+    end
+  end
+end

data/lib/docusigner/multipart.rb

@@ -0,0 +1,122 @@
+require 'net/http/post/multipart'
+require 'active_support/all'
+
+# this class leverages some parts of the multipart-post gem,
+#   but we need to change some headers
+module Docusigner
+  module Multipart
+    module Multipartable
+      DEFAULT_BOUNDARY = "-----------RubyMultipartPost"
+      def initialize(path, params, headers={}, opts = {})
+        boundary = opts[:boundary] || DEFAULT_BOUNDARY
+        super(path, headers)
+        parts = params.map {|v| Docusigner::Multipart::Parts.build(boundary, v, opts)}
+        parts << ::Parts::EpiloguePart.new(boundary)
+        ios = parts.map{|p| p.to_io }
+        self.set_content_type("multipart/form-data", { "boundary" => boundary })
+        self.content_length = parts.inject(0) {|sum,i| sum + i.length }
+        self.body_stream = CompositeReadIO.new(*ios)
+      end
+    end
+
+    module Parts
+      def self.build(boundary, value, opts = {})
+        if value.is_a?(Array)
+          self.build(boundary, value.first, opts.merge(value.last))
+        elsif value.is_a?(String)
+          DataPart.new(boundary, value, opts)
+        elsif value.is_a?(UploadIO)
+          DocumentPart.new(boundary, value, opts)
+        else
+          DataPart.new(boundary, value, opts)
+        end
+      end
+
+      class DataPart < StringIO
+        def initialize(boundary, data, opts = {})
+          @format = opts[:format] || :json
+          @content_type = {
+            :json => "application/json",
+            :xml => "application/xml"
+          }[@format]
+          super(build(boundary, data, opts))
+        end
+        def to_io
+          self
+        end
+        protected
+        def build(boundary, value, opts = {})
+          [
+            "--#{boundary}",
+            "Content-Type: #{@content_type}",
+            "Content-Disposition: form-data",
+            "",
+            value,
+            ""
+          ].join("\r\n")
+        end
+      end
+
+      class DocumentPart
+        attr_reader :length
+        def initialize(boundary, upload_io, opts = {})
+          @upload_io = upload_io
+          head = build(boundary, @upload_io, opts)
+          foot = "\r\n"
+          @output_io = CompositeReadIO.new(StringIO.new(head), @upload_io.io, StringIO.new(foot))
+          @length = head.length + file_length + foot.length
+        end
+        def to_io
+          @output_io
+        end
+        protected
+
+        def file_length
+          @file_length ||= @upload_io.respond_to?(:length) ? @upload_io.length : File.size(@upload_io.local_path)
+        end
+        
+        def build(boundary, io, opts = {})
+          [
+            "--#{boundary}",
+            %(Content-Type: #{io.content_type}),
+            %(Content-Disposition: file; filename="#{opts[:name]}"; documentId=#{opts[:document_id]}),
+            %(Content-Length: #{file_length}),
+            "",
+            ""
+          ].join("\r\n")
+        end
+      end
+    end
+
+    class Post < Net::HTTP::Post
+      include Docusigner::Multipart::Multipartable
+    end
+
+    class Put < Net::HTTP::Put
+      include Docusigner::Multipart::Multipartable
+    end
+
+    module Resource
+      def add_document(file, document_id)
+        @documents ||= []
+        @documents << [file, {:document_id => document_id}]
+      end
+
+      def encode
+        if documents.present?
+          [super, *documents]
+        else
+          super
+        end
+      end
+
+      protected
+
+      def documents
+        @documents ||= []
+      end
+    end
+
+  end
+end
+

data/lib/docusigner/oauth2.rb

@@ -0,0 +1,24 @@
+module Docusigner
+  class Oauth2 < Docusigner::Base
+    singleton
+
+    class << self
+      def token(username, password, integrator_key)
+        @headers = {
+          "Accept" => "application/json",
+          "Content-Type" => "application/x-www-form-urlencoded"
+        }
+        body = "grant_type=password&client_id=#{integrator_key}&username=#{username}&password=#{password}&scope=api"
+        resp = post(:token, {}, body) 
+        format.decode(resp.body)["access_token"]
+      end
+
+      def revoke(token)
+        @headers = {
+          "Authorization" => "Bearer #{token}"
+        }
+        post(:revoke, {}, "")
+      end
+    end
+  end
+end

data/lib/docusigner/recipient.rb

@@ -0,0 +1,17 @@
+module Docusigner
+  class Recipient < Docusigner::Base
+    module Status
+      CREATED       = "created"
+      SENT          = "sent"
+      DELIVERED     = "delivered"
+      SIGNED        = "signed"
+      DECLINED      = "declined"
+      COMPLETED     = "completed"
+      FAX_PENDING   = "faxpending"
+      AUTORESPONDED = "autoresponded"
+    end
+
+    belongs_to :envelope
+    has_many :tabs
+  end
+end

data/lib/docusigner/settings.rb

@@ -0,0 +1,21 @@
+module Docusigner
+  class Settings < Docusigner::Base
+    singleton
+
+    belongs_to :account
+
+    def [](setting)
+      as = accountSettings.detect{|as| as.name == setting}
+      as ? as.attributes["value"] : nil
+    end
+
+    class << self
+      def instantiate_record(record, prefix_options)
+        super({
+          :accountSettings => record,
+          :account_id => prefix_options[:account_id]
+        }, prefix_options)
+      end
+    end
+  end
+end

data/lib/docusigner/tab.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class Tab < Docusigner::Base
+    belongs_to :recipient
+  end
+end

data/lib/docusigner/template.rb

@@ -0,0 +1,5 @@
+module Docusigner
+  class Template < Docusigner::Base
+    belongs_to :account
+  end
+end

data/lib/docusigner/user.rb

@@ -0,0 +1,29 @@
+module Docusigner
+  class User < Docusigner::Base
+    belongs_to :account
+
+    # DocuSign does not permit this endpoint
+    def update
+      raise "Not permitted"
+    end
+
+    # the create endpoint requires attributes to be nested under newUsers
+    def as_json
+      { "newUsers" => [super] }
+    end
+
+    protected
+
+    def id_from_response(response)
+      json = JSON.parse(response.body)
+      json["newUsers"].first["userId"]
+    end
+
+    def load(attributes, remove_root = false)
+      if attributes.is_a?(Array)
+        attributes = attributes.first
+      end
+      super(attributes, remove_root)
+    end
+  end
+end

data/lib/docusigner.rb

@@ -0,0 +1,25 @@
+require 'docusigner/base'
+module Docusigner
+  # extensions
+  autoload :Connection, "docusigner/connection"
+  autoload :Multipart, "docusigner/multipart"
+
+  # REST models
+  autoload :Account, "docusigner/account"
+  autoload :BillingPlan, "docusigner/billing_plan"
+  autoload :Brand, "docusigner/brand"
+  autoload :CustomField, "docusigner/custom_field"
+  autoload :Document, "docusigner/document"
+  autoload :Envelope, "docusigner/envelope"
+  autoload :Folder, "docusigner/folder"
+  autoload :Group, "docusigner/group"
+  autoload :LoginInformation, "docusigner/login_information"
+  autoload :Recipient, "docusigner/recipient"
+  autoload :Settings, "docusigner/settings"
+  autoload :Tab, "docusigner/tab"
+  autoload :Template, "docusigner/template"
+  autoload :User, "docusigner/user"
+
+  # other models
+  autoload :Oauth2, "docusigner/oauth2"
+end