agree2 0.1.1

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Extra Eagle LLC
+
+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.rdoc

@@ -0,0 +1,165 @@
+= Agree2 Client
+
+Agree2 (https://agree2.com) is a site for creating and maintaining contracts. 
+
+This Client library will let you integrate Agree2 into your own web applications to create full legal contracts between you and your users or between your users.
+
+== Install the Agree2 gem
+
+The Agree2 client is installed as a ruby gem:
+
+  sudo gem install agree2
+
+The source is available on github https://github.com/pelle/agree2-client/tree/master .
+
+== Getting Started
+
+First of all you need to signup with https://agree2.com. 
+
+Now go to the page http://agree2.dev/client_applications and register an application.
+
+Find the snippet of code on your client application page called "Example using your own AccessToken". This provides you everything to get started creating agreements under you own account. It should something like this:
+
+  @client=Agree2::Client.new "DM0VybBbeTc6GfFSF1WbQ","aVmgGmQ1WOjsbbSZbrPcT4qet6IMa2tqJebaeyIBs"
+  @user=@client.user "zEHUnKDNuLGXQuicFWZRpQ","0VM3ESRl3rGtg95Wa2JsOFWmu4E78lNHfvMy1j4UtQ"
+
+If you wanted to list all the agreements you've got in your account you would do the following:
+
+  @user.agreements
+
+Creating a new agreement:
+
+  @agreement=@user.agreements.create(:title=>"User Agreement",:body=>"This is the body of the agreement")
+  @agreement.to_url # Returns the agreement's url
+  redirect_to @agreement.to_url # Redirect to agreements url in Rails
+  
+Invite a party:
+
+  @party=@agreement.parties.create :role=>"client",:first_name=>"Joe",:last_name=>"Bloggs",:email=>"joe@blogs.inv",:organization_name=>"Big Inc"
+  redirect_to @party.present # Redirect user in an authenticated way to agreement
+
+List the parties to an agreement:
+
+  @agreement.parties
+
+By default new agreements are in draft mode, ready for further customization. For the parties to be able to accept the agreement you must finalize it:
+ 
+  @agreement.finalize!
+  
+== Using Templates
+
+In most day to day use you will probably be using templates to create agreements. You can create your own templates or use our growing library of public templates (https://agree2.com/masters/public).
+
+As an example lets use this "Confidentiality Agreement for access to source code" (https://agree2.com/masters/b4f9a904efaab5ad71f695824c997c332b955876). 
+
+You could instantiate the template using the long code that comes at the end of the url:
+
+  @template=@agree2_user.templates.find "b4f9a904efaab5ad71f695824c997c332b955876"
+
+We have actually made it even easier though. Each template has it's own Ruby version that you can download. If you click on "Tools" and then "Instant Ruby API" you will find it customized for your own use. In our example you can find it at:
+
+https://agree2.com/masters/b4f9a904efaab5ad71f695824c997c332b955876.rb
+
+Save this file and require it into your application. This will also provide you with an instance of the template in @template.
+
+=== Preparing an Agreement from a Template
+
+To create an agreement with no customizations simply do:
+
+  @agreement=@template.prepare
+
+Templates have user defined fields that can be filled out by the application. This is where it gets interesting:
+
+  @agreement=@template.prepare :holder => "John Doe",
+         :holder_info => "john@gmail.inv",
+         :coder => "Phil Armonic",
+         :coder_info => "phil@gmail.inv",
+         :project => "Spoogle.com",
+         :svn => "http://svnhost.inv/spoogle"
+
+Each of the custom fields from the template is now directly available in the agreement:
+  
+  puts @agreement.holder
+  > "John Doe"
+  
+You can also get the full list of fields using:
+
+  @agreement.fields
+
+=== Preparing Agreement from a Template and adding Parties
+
+To reduce the amount of network activity between your servers and ours you can create an agreement from a template and add parties in one step.
+
+  @agreement=@template.prepare {
+     :holder => "John Doe",
+     :holder_info => "john@gmail.inv",
+     :coder => "Phil Armonic",
+     :coder_info => "phil@gmail.inv",
+     :project => "Spoogle.com",
+     :svn => "http://svnhost.inv/spoogle"
+    },{
+      :coder=>{ 
+        :first_name=>"Phil",
+        :last_name=>"Armonic",
+        :email=>"phil@gmail.inv"
+      },
+      :holder=>{ 
+        :first_name=>"John",
+        :last_name=>"Doe",
+        :email=>"john@gmail.inv",
+        :organization_name=>"Spoogle Inc"
+      }
+    }
+
+The above creates the agreement, adds the 2 parties and sends emails to them.
+
+You can also add your applications user in agree2 as a party without having to repeat all the information:
+
+@agreement=@template.prepare {
+   :holder => "John Doe",
+   :holder_info => "john@gmail.inv",
+   :coder => "Phil Armonic",
+   :coder_info => "phil@gmail.inv",
+   :project => "Spoogle.com",
+   :svn => "http://svnhost.inv/spoogle"
+  },{
+    :coder=>{ 
+      :first_name=>"Phil",
+      :last_name=>"Armonic",
+      :email=>"phil@gmail.inv"
+    }
+  },"holder"
+
+This does the same as the first example except "holder" will have the details from your user account.
+
+=== Preparing and signing an agreeement from the API
+
+Lets say you want to create an agreement, add the parties and sign it so your user can go straight to it to accept it. Agree2 offers the possibility of signing an agreement during the creation process. Not all accounts have access to this feature.
+
+The signing process is done using the OAuth protocol we use for authentication. We also only allow you to sign on behalf of the application's user.
+
+  @agreement=@template.prepare_and_sign {
+     :holder => "John Doe",
+     :holder_info => "john@gmail.inv",
+     :coder => "Phil Armonic",
+     :coder_info => "phil@gmail.inv",
+     :project => "Spoogle.com",
+     :svn => "http://svnhost.inv/spoogle"
+    },{
+      :coder=>{ 
+        :first_name=>"Phil",
+        :last_name=>"Armonic",
+        :email=>"phil@gmail.inv"
+      }
+    },"holder"
+
+The final parameter "holder" is optional. It will add you as a party with the role "application" by default.
+
+== About Agree2 Client
+
+Author::    Pelle Braendgaard (http://stakeventures.com)
+Copyright:: Copyright (c) 2008 Extra Eagle LLC
+License::   MIT
+Git::       https://github.com/pelle/agree2-client/tree/master
+
+This client library allows you to integrate Agree2 into your application.

data/Rakefile

@@ -0,0 +1,97 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+require 'yaml'
+namespace :rdoc do |ns|
+  Rake::RDocTask.new(:doc) do |rd|
+    rd.main = "README.rdoc"
+    rd.rdoc_dir = 'doc'
+    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+    rd.options << "-t Agree2"
+  end
+
+  desc 'Publish RDoc to RubyForge.'
+  task :publish_docs => [:doc] do
+    config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+    host = "#{config["username"]}@rubyforge.org"
+
+    remote_dir = "/var/www/gforge-projects/agree2"
+    local_dir = 'doc'
+
+    sh %{rsync -av --delete #{local_dir}/ #{host}:#{remote_dir}}
+  end
+  
+end
+
+namespace :spec do |ns|
+  desc "Run all examples"
+  Spec::Rake::SpecTask.new('spec') do |t|
+    t.spec_files = FileList['spec/*.rb']
+  end
+
+  desc "Run rcov"
+  Spec::Rake::SpecTask.new('rcov') do |t|
+    t.spec_files = FileList['spec/*.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude','gems,spec']
+  end
+end
+
+namespace :gem do |gem|
+  File.open( 'agree2.gemspec') do |f|
+    @gem=eval(f.read)
+    @version=@gem.version.to_s
+  end
+  
+  Rake::GemPackageTask.new @gem do |pkg|
+    pkg.need_tar = true
+    pkg.need_zip = true
+  end
+
+  desc 'Install the package as a gem.'
+  task :install => [:clean, :package] do
+    gem = Dir['pkg/*.gem'].first
+    sh "sudo gem install --local #{gem}"
+  end
+
+  
+  desc 'Package and upload the release to rubyforge.'
+  task :release => [:clean, :package] do |t|
+    pkg = "pkg/#{name}-#{@version}"
+
+    if $DEBUG then
+      puts "release_id = rf.add_release #{rubyforge_name.inspect}, #{name.inspect}, #{@version.inspect}, \"#{pkg}.tgz\""
+      puts "rf.add_file #{rubyforge_name.inspect}, #{name.inspect}, release_id, \"#{pkg}.gem\""
+    end
+
+    rf = RubyForge.new.configure
+    puts "Logging in"
+    rf.login
+
+#    c = rf.userconfig
+#    c["release_notes"] = description if description
+#    c["release_changes"] = changes if changes
+#    c["preformatted"] = true
+
+    files = ["#{pkg}.tgz",
+             "#{pkg}.zip",
+             "#{pkg}.gem"].compact
+
+    puts "Releasing #{name} v. #{@version}"
+    rf.add_release rubyforge_name, name, @version, *files
+  end
+  
+end
+
+desc "Clean up all dirt"
+task :clean => [ "rdoc:clobber_doc", "gem:clobber_package" ] do
+   %w(diff diff.txt email.txt ri *.gem *~ **/*~ *.rbc **/*.rbc coverage).each do |pattern|
+    files = Dir[pattern]
+    rm_rf files, :verbose => true unless files.empty?
+  end
+end
+
+task :default=>[:spec]

data/lib/agree2/agreement.rb

@@ -0,0 +1,71 @@
+module Agree2
+  class Agreement<Base
+    attr_serializable :permalink,:title,:body,:created_at,:updated_at,:smart_fields,:state,:active_version,
+                      :version,:digest,:finalized_at,:finalized_at,:terminated_at,:activated_at,:valid_to
+    
+    alias_method :fields,:smart_fields
+    # Returns the parties to the agreement
+    def parties
+      @parties||=Agree2::ProxyCollection.new self,"#{self.path}/parties",'Party'
+    end
+    
+    def parties=(values)
+      @parties=Agree2::ProxyCollection.new self,"#{self.path}/parties",'Party',values
+    end
+
+    def to_param #:nodoc:
+      permalink
+    end
+    
+    def respond_to?(symbol, include_priv = false)  #:nodoc:
+      return true if super symbol,include_priv
+      return false if fields.nil?||fields.empty?
+      method=symbol.to_s
+      if method=~/(.+)=$/
+        field=$1
+        setter=true
+      else
+        field=method
+        setter=false
+      end
+      fields.has_key?(field)
+    end
+    
+    # Finalize marks a draft agreement as being ready to accept
+    def finalize!
+      user.post(path+"/finalize")==" "
+    end
+    
+    protected
+    
+    def attributes_for_save #:nodoc:
+      if new_record?
+        {self.class.singular_name=>attributes}
+      else
+        {"fields"=>fields}
+      end
+    end
+    
+    def method_missing(method, *args, &block)  #:nodoc:
+      return super(method, *args, &block) if fields.nil?||fields.empty?
+      method=method.to_s
+      if method=~/(.+)=$/
+        field=$1
+        setter=true
+      else
+        field=method
+        setter=false
+      end
+      if fields.has_key?(field)
+        if setter
+          fields[field]=args.first
+        else
+          fields[field]
+        end
+      else
+        super method, *args, &block
+      end
+    end
+    
+  end
+end

data/lib/agree2/base.rb

@@ -0,0 +1,147 @@
+require 'json'
+require 'set'
+module Agree2
+  # The superclass of all Agree2 Resource objects.
+  class Base
+    class<<self
+      
+      def attr_serializable(*attributes) #:nodoc:
+        attributes.map!{|a|a.to_sym}
+        write_inheritable_attribute("serializable_attributes", 
+          Set.new(attributes) + 
+          (serializable_attributes || []))
+        attr_accessor *attributes
+      end
+
+      # Returns an array of all the attributes that have been made accessible to mass-assignment.
+      def serializable_attributes # :nodoc:
+        read_inheritable_attribute("serializable_attributes")
+      end
+      
+      def collection_path #:nodoc:
+        "/#{collection_name}"
+      end
+
+      def instance_path(id) #:nodoc:
+        "#{collection_path}/#{id}"
+      end
+
+      def collection_name #:nodoc:
+        self.to_s.demodulize.tableize
+      end
+
+      def singular_name #:nodoc:
+        self.to_s.demodulize.underscore.singularize
+      end
+      
+      # Gets an instance of a resource
+      def get(container,id)
+        user=(container.is_a?(User) ? container : container.user)
+        new( container, user.get(container.path+instance_path(id)))
+      end
+      
+    end
+
+    attr_accessor :user,:container
+        
+    def initialize(container,fields={})#:nodoc:
+      @container=container
+      @user=(container.is_a?(User) ? container : container.user)
+      if fields.is_a?(Hash)
+        load_attributes(fields)
+      else
+        load_json(fields)
+      end
+    end
+    
+    # Has this record been saved to the server yet?
+    def new_record?
+      @from_wire!=true
+    end
+    
+    # Reloads the object from Agree2's servers
+    def reload
+      load_json(user.get(path))
+    end
+
+    # Destroys the object from Agree2's servers
+    def destroy
+      user.delete(path)
+    end
+    
+    # Returns the full URL for the object
+    def to_url
+      "#{AGREE2_URL}#{path}"
+    end
+    
+    # Returns the relative path to the object
+    def path #:nodoc:
+      self.container.path+self.class.instance_path(to_param)
+    end
+    
+    # The primary key of the object
+    def to_param #:nodoc:
+      id
+    end
+    
+    # Saves the record to the server
+    def save
+      if new_record?
+        load_json(@user.post("#{self.container.path}/#{self.class.collection_name}",attributes_for_save))
+      else
+        load_json(@user.put("#{path}",attributes_for_save))
+      end
+    end
+    
+    # Get the primary attributes of an object as a hash
+    def attributes
+      self.class.serializable_attributes.inject({}) do |h,field|
+        value=self.send(field)
+        h[field]=value if value
+        h
+      end
+    end
+    
+    protected
+    
+    def attributes_for_save #:nodoc:
+      {self.class.singular_name=>attributes}
+    end
+    
+    def decode(element) #:nodoc:
+        for field in self.class.serializable_attributes
+          method_name="#{field.to_s}=".to_sym
+          self.send(method_name, (element/field.to_sym).innerHTML) if self.respond_to?(method_name)
+        end
+        self
+    end
+
+    def load_attributes(attributes) #:nodoc:
+      @attributes=attributes
+      attributes.each_pair do |key,value|
+        method_name="#{key.to_s}=".to_sym
+        self.send(method_name,value) if self.respond_to?(method_name)
+      end
+    end
+        
+    def load_json(json) #:nodoc:
+      @from_wire=true
+      load_attributes(JSON.parse(json))
+    end
+#    private
+#    
+#    def method_missing(method_symbol, *arguments) #:nodoc:
+#      method_name = method_symbol.to_s
+#
+#      case method_name.last
+#        when "="
+#          self.attributes[method_name.first(-1)] = arguments.first
+#        when "?"
+#          self.attributes[method_name.first(-1)]
+#        else
+#          self.attributes.has_key?(method_name) ? self.attributes[method_name] : super
+#      end
+#    end
+#    
+  end
+end

data/lib/agree2/client.rb

@@ -0,0 +1,101 @@
+require 'oauth/consumer'
+
+module Agree2
+  # If you haven't done so already register your application at https://agree2.com/client_applications
+  #
+  # The full authorization process works like this over 2 controller actions (This example is in Rails):
+  #
+  #   def request_token
+  #     @client = Agree2::Client.new "key","secret"
+  #     @request_token = @client.get_request_token
+  #     
+  #     # Store the token in a model in your applications mapping it to your user
+  #     Agree2RequestToken.create :user=>current_user,:token=>@request_token.token,:secret=>@request_token.secret
+  #     redirect_to @request_token.authorize_url
+  #   end
+  #
+  #   # The user authorizes the token on the Agree2 web site and is redirected to the authorize_url you setup when you registered your application at:
+  #   # https://agree2.com/client_applications
+  #   def authorize
+  #     @client = Agree2::Client.new "key","secret"
+  #     
+  #     # Load the request token from your Agree2RequestToken through your user model
+  #     @request_token = current_user.agree2_request_token.request_token
+  #     
+  #     # Exchange the authorized request token for a more permanent User token on the Agree2 site
+  #     @user_client=@client.user_from_request_token(@request_token)
+  #     
+  #     # Store the Agree2 user data in your own model
+  #     @agree2_user=Agree2User.create :user=>current_user,:token=>@user_client.token,:secret=>@user_client.secret
+  #  end
+  #
+  
+  class Client
+    attr_accessor :consumer
+    
+    # Initialize the Agree2 Client
+    #
+    # === Required Fields
+    #
+    # * <tt>key</tt> - The Consumer Key
+    # * <tt>secret</tt> - The Consumer Secret
+    #
+    # To get these register your application at: https://agree2.com/client_applications
+    def initialize(key,secret)
+      @consumer=OAuth::Consumer.new(key,secret,{:site=>AGREE2_URL})
+    end
+    
+    # initialize a new user object with the given token and secret. The user object is what you use to do most of the work.
+    # Use this method when you need to create a user object from a token and secret you have stored in your applications database.
+    #
+    # === Required Fields
+    #
+    # * <tt>token</tt> - This is the authorized Token
+    # * <tt>secret</tt> - This is the authorized Token Secret
+    #
+    def user(token,token_secret)
+      User.new(self,token,token_secret)
+    end
+    
+    # Start the process of authorizing a token for an Agree2 user.
+    #
+    # Example:
+    #     @request_token = @client.get_request_token
+    #     redirect_to @request_token.authorize_url
+    #
+    def get_request_token
+      consumer.get_request_token
+    end
+    
+    # Exchange an Authorized RequestToken for a working user object
+    #
+    # === Required Field
+    # 
+    # * <tt>request_token</tt> The Request token created using get_request_token and authorized on Agree2 by your user
+    #
+    # Example:
+    #
+    #     @user_client = @client.user_from_request_token(@request_token)
+    #
+    def user_from_request_token(request_token)
+      access_token=request_token.get_access_token
+      user(access_token.token,access_token.secret)
+    rescue Net::HTTPServerException=>e
+      if e.response.code=='401'
+        raise Agree2Exception,"The user has not authorized this request token",caller
+      else
+        raise
+      end
+    end
+
+    # Returns your consumer key
+    def key
+      @consumer.key
+    end
+    
+    # Returns your consumer secret
+    def secret
+      @consumer.secret
+    end
+  end
+end

data/lib/agree2/party.rb

@@ -0,0 +1,23 @@
+module Agree2
+  class Party<Base
+    attr_serializable :id,:role,:email,:first_name,:last_name,:created_at,:updated_at,:organization_name
+    alias_method :agreement,:container  
+    
+    # Creates a one time signed url to redirect your user to their acceptance page. This url is only valid once. Call again to
+    # redirect your user to the agreement again.
+    def present
+      path="/present/#{agreement.permalink}/to/#{email}"
+      AGREE2_URL+user.client.consumer.create_signed_request(:get,path,user.access_token,{:scheme=>:query_string}).path
+    end
+    
+    def self.validate_parties_hash(parties)  #:nodoc:
+      parties&&parties.each{|r,p| validate_party_hash(p)}
+      true
+    end
+    
+    def self.validate_party_hash(p)  #:nodoc:
+      raise ArgumentError,"Your parties are missing required fields" if [:first_name,:last_name,:email].find{|k| !p.include?(k)}
+      return true
+    end
+  end
+end