@@ -1,7 +1,21 @@ = 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. + +== 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. + + + Author:: Pelle Braendgaard (http://stakeventures.com) -Copyright:: Copyright (c) 2008 Pelle Braendgaard +Copyright:: Copyright (c) 2008 Extra Eagle LLC License:: MIT Git:: https://github.com/pelle/agree2-client/tree/master README.rdoc @@ -3,12 +3,27 @@ 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| @@ -25,4 +40,58 @@ namespace :spec do |ns| 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] Rakefile @@ -13,8 +13,59 @@ module Agree2 @parties=Agree2::ProxyCollection.new self,"#{self.path}/parties",'Party',values end - def to_param + 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 \ No newline at end of file lib/agree2/agreement.rb @@ -18,28 +18,35 @@ module Agree2 read_inheritable_attribute("serializable_attributes") end - def instance_url(id) #:nodoc: - "/#{collection_name}/#{id}" + 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_url(id)+".json")) + new( container, user.get(container.path+instance_path(id)+".json")) end end - attr_accessor :user,:attributes,:container + attr_accessor :user,:container def initialize(container,fields={})#:nodoc: @container=container @user=(container.is_a?(User) ? container : container.user) - attributes={} if fields.is_a?(Hash) load_attributes(fields) else @@ -47,9 +54,19 @@ module Agree2 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+".json")) + 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 @@ -59,7 +76,7 @@ module Agree2 # Returns the relative path to the object def path #:nodoc: - self.container.path+self.class.instance_url(to_param) + self.container.path+self.class.instance_path(to_param) end # The primary key of the object @@ -67,8 +84,30 @@ module Agree2 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 @@ -78,6 +117,7 @@ module Agree2 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) @@ -85,6 +125,7 @@ module Agree2 end def load_json(json) #:nodoc: + @from_wire=true load_attributes(JSON.parse(json)) end # private lib/agree2/base.rb @@ -3,6 +3,8 @@ module Agree2 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 lib/agree2/party.rb @@ -1,7 +1,7 @@ require 'json' module Agree2 class ProxyCollection - alias_method :proxy_respond_to?, :respond_to? + alias_method :proxy_respond_to?, :respond_to? #:nodoc: instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|^send$|proxy_)/ } attr_accessor :user,:path,:singular def initialize(container,path,class_name=nil,values=nil) @@ -18,44 +18,55 @@ module Agree2 end end + # Builds an instance of the record + def build(attributes={}) + @klass.new @container,attributes + end + + # Builds and saves and instance of the record + def create(attributes={}) + build(attributes).save + end + + # Finds the instance given the id def find(id) @klass.get @container,id end - def respond_to?(symbol, include_priv = false) + def respond_to?(symbol, include_priv = false) #:nodoc: proxy_respond_to?(symbol, include_priv) || (load_target && @target.respond_to?(symbol, include_priv)) end # Explicitly proxy === because the instance method removal above # doesn't catch it. - def ===(other) + def ===(other) #:nodoc: load_target other === @target end protected - def parse_json(json) + def parse_json(json) #:nodoc: instantiate_items(JSON.parse(json)) end - def instantiate_items(list=[]) + def instantiate_items(list=[]) #:nodoc: list.collect{|e|instantiate_item(e)} end - def instantiate_item(attributes={}) + def instantiate_item(attributes={}) #:nodoc: @klass.new @container,attributes end - def load_target - @target||=parse_json(@user.get("#{self.path}.json")) + def load_target #:nodoc: + @target||=parse_json(@user.get("#{self.path}")) end - def reset + def reset #:nodoc: @target=nil end - def method_missing(method, *args, &block) + def method_missing(method, *args, &block) #:nodoc: if load_target @target.send(method, *args, &block) end lib/agree2/proxy_collection.rb @@ -94,7 +94,7 @@ module Agree2 protected def raw_prepare(params={}) #:nodoc: - user.post("/masters/#{permalink}/prepare",params) + Agreement.new @user, user.post("/masters/#{permalink}/prepare",params) end end end \ No newline at end of file lib/agree2/template.rb @@ -1,7 +1,7 @@ +AGREE2_JSON_HEADERS={'Content-Type'=>'application/json','Accept'=>'application/json'} module Agree2 class User attr_accessor :client,:access_token - def initialize(client,key,secret) @client=client @access_token=OAuth::AccessToken.new @client.consumer,key,secret @@ -16,23 +16,23 @@ module Agree2 end def get(path) - handle_response @access_token.get(path) + handle_response @access_token.get(path,AGREE2_JSON_HEADERS) end def head(path) - handle_response @access_token.head(path) + handle_response @access_token.head(path,AGREE2_JSON_HEADERS) end def post(path,data=nil) - handle_response @access_token.post(path,(data ? data.to_json : nil),{'Content-Type'=>'application/json'}) + handle_response @access_token.post(path,(data ? data.to_json : nil),AGREE2_JSON_HEADERS) end def put(path,data=nil) - handle_response @access_token.put(path,(data ? data.to_json : nil),{'Content-Type'=>'application/json'}) + handle_response @access_token.put(path,(data ? data.to_json : nil),AGREE2_JSON_HEADERS ) end def delete(path) - handle_response @access_token.delete(path) + handle_response @access_token.delete(path,AGREE2_JSON_HEADERS) end # OAuth Stuff below here @@ -56,6 +56,8 @@ module Agree2 case response.code when "200" response.body + when "201" + response.body when "302" if response['Location']=~/(#{AGREE2_URL})\/(.*)$/ parts=$2.split('/') lib/agree2/user.rb @@ -10,7 +10,11 @@ describe Agree2::Agreement do before(:each) do @agreement=Agree2::Agreement.new(@user,{:title=>"My Title",:body=>"My Body"}) end - + + it "should have attribute hash" do + @agreement.attributes.should=={:title=>"My Title",:body=>"My Body"} + end + it "should have a user" do @agreement.user.should==@user end @@ -23,9 +27,32 @@ describe Agree2::Agreement do @agreement.body.should=="My Body" end + it "should be new record" do + @agreement.should be_new_record + end + + describe "Save to Server" do + before(:each) do + @user.should_receive(:post).with("/agreements",{'agreement'=>{:title=>"My Title",:body=>"My Body"}}).and_return(@json) + end + + it "should save and return true" do + @agreement.save + end + + it "should no longer be new record" do + @agreement.save + @agreement.should_not be_new_record + end + + it "should have a permalink" do + @agreement.save + @agreement.permalink.should_not be_nil + end + end end - describe "from xml" do + describe "from json" do before(:each) do @agreement=Agree2::Agreement.new(@user,@json) @@ -67,8 +94,66 @@ describe Agree2::Agreement do "amount"=> "100", "currency"=> "USD" } - end + end + + it "should have methods defined for fields" do + @agreement.amount.should=="100" + @agreement.currency.should=="USD" + end + [:amount,:currency].each do |field| + it "should support setting the value" do + @agreement.send("#{field.to_s}=".to_sym,"test this") + @agreement.send(field).should=="test this" + @agreement.fields[field.to_s].should=="test this" + end + + it "should have respond_to wired for field accessor" do + @agreement.respond_to?(field).should==true + end + + it "should have respond_to wired for field setter" do + @agreement.respond_to?("#{field.to_s}=".to_sym).should==true + end + end + + it "should not be new record" do + @agreement.should_not be_new_record + end + it "should reload" do + @user.should_receive(:get).with("/agreements/hello").and_return(@json) + @agreement.reload + end + + it "should destroy" do + @user.should_receive(:delete).with("/agreements/hello").and_return("") + @agreement.destroy + end + + it "should finalize" do + @user.should_receive(:post).with("/agreements/hello/finalize").and_return(" ") + @agreement.finalize!.should==true + end + + describe "Save to Server" do + before(:each) do + @user.should_receive(:put).with("/agreements/hello",{"fields"=>@agreement.fields}).and_return(@json) + end + + it "should save and return true" do + @agreement.save + end + + it "should not a be new record" do + @agreement.save + @agreement.should_not be_new_record + end + + it "should have a permalink" do + @agreement.save + @agreement.permalink.should_not be_nil + end + end end describe "load from server" do @@ -94,7 +179,12 @@ describe Agree2::Agreement do do_get @agreement.permalink.should=="hello" end - + + it "should not be new record" do + do_get + @agreement.should_not be_new_record + end + end end spec/agreement_spec.rb @@ -9,7 +9,6 @@ "agreement_id": 757, "user_id": null, "first_name": "Bob", - "accept_code": "d373b3dc17b7177aa0626e6ce7f449fcc3ca7c9c", "last_name": "Wildcat", "email": "bob@gmail.inv", "created_at": "2008/08/12 22:04:51 +0000" spec/fixtures/party.json @@ -11,13 +11,17 @@ describe Party do @client=Agree2::Client.new "client_key","client_secret" @user=Agree2::User.new(@client,"token","token_secret") @agreement=Agreement.new @user,{:permalink=>'hello'} + @json=IO.read(File.join(File.dirname(__FILE__),"fixtures","party.json")) end - describe "Built from hash" do + describe "Create new" do before(:each) do - @party=Party.new(@agreement,{:first_name=>"Bob",:last_name=>"Wildcat",:email=>'bob@gmail.inv',:id=>1102}) + @party=Party.new(@agreement,{:first_name=>"Bob",:last_name=>"Wildcat",:email=>'bob@gmail.inv'}) end - + it "should be new record" do + @party.should be_new_record + end + it "should have agreement" do @party.agreement.should==@agreement end @@ -34,32 +38,32 @@ describe Party do @party.last_name.should=="Wildcat" end - it "should have a path" do - @party.path.should=="/agreements/hello/parties/1102" - end - - it "should have a url" do - @party.to_url.should=="https://agree2.com/agreements/hello/parties/1102" - end - - it "should generate present url" do - present_url=@party.present - present_url=~/^(http.*)\?(.*)$/ - $1.should=="https://agree2.com/present/hello/to/bob@gmail.inv" - end - - it "should verify present url" do - present_url=@party.present - request = Rack::Request.new(Rack::MockRequest.env_for(present_url)) - OAuth::Signature.verify(request,{:consumer=>@client.consumer,:token=>@user.access_token}).should==true + describe "Save to Server" do + before(:each) do + @user.should_receive(:post).with("/agreements/hello/parties", + {'party'=>{:first_name=>"Bob",:last_name=>"Wildcat",:email=>'bob@gmail.inv'}}).and_return(@json) + end + it "should save and return true" do + @party.save + end + + it "should no longer be new record" do + @party.save + @party.should_not be_new_record + end + + it "should have a permalink" do + @party.save + @party.id.should==1102 + end end + end describe "from json" do before(:each) do - @json=IO.read(File.join(File.dirname(__FILE__),"fixtures","party.json")) @party=Party.new(@agreement,@json) end @@ -87,6 +91,31 @@ describe Party do @party.to_url.should=="https://agree2.com/agreements/hello/parties/1102" end + it "should generate present url" do + present_url=@party.present + present_url=~/^(http.*)\?(.*)$/ + $1.should=="https://agree2.com/present/hello/to/bob@gmail.inv" + end + + it "should verify present url" do + present_url=@party.present + request = Rack::Request.new(Rack::MockRequest.env_for(present_url)) + OAuth::Signature.verify(request,{:consumer=>@client.consumer,:token=>@user.access_token}).should==true + + end + + describe "Save to Server" do + before(:each) do + @user.should_receive(:put).with("/agreements/hello/parties/1102", + {'party'=>@party.attributes}).and_return(@json) + end + + it "should save and return true" do + @party.save + end + + end + end end spec/party_spec.rb @@ -62,6 +62,19 @@ describe Agree2::ProxyCollection do IO.read(File.join(File.dirname(__FILE__),"fixtures","agreement.json"))) @agreements.find('something') end + + it "should instantiate a new party" do + Agree2::Agreement.should_receive(:new).with(@user,{:title=>"Test",:body=>"Body"}) + @agreements.build :title=>"Test",:body=>"Body" + end + + it "should create and save a new party" do + @agreement=mock("agreement") + Agree2::Agreement.should_receive(:new).with(@user,{:title=>"Test",:body=>"Body"}).and_return(@agreement) + @agreement.should_receive(:save) + @agreements.create :title=>"Test",:body=>"Body" + end + end describe "nested load" do @@ -94,6 +107,18 @@ describe Agree2::ProxyCollection do IO.read(File.join(File.dirname(__FILE__),"fixtures","party.json"))) @parties.find(123) end + + it "should instantiate a new party" do + Agree2::Party.should_receive(:new).with(@agreement,{:first_name=>"Bob",:last_name=>"Galbraith",:email=>'bob@bob.inv'}) + @parties.build :first_name=>"Bob",:last_name=>"Galbraith",:email=>'bob@bob.inv' + end + + it "should create and save a new party" do + @party=mock("party") + Agree2::Party.should_receive(:new).with(@agreement,{:first_name=>"Bob",:last_name=>"Galbraith",:email=>'bob@bob.inv'}).and_return(@party) + @party.should_receive(:save) + @parties.create :first_name=>"Bob",:last_name=>"Galbraith",:email=>'bob@bob.inv' + end end end \ No newline at end of file spec/proxy_collection_spec.rb @@ -7,6 +7,8 @@ describe Agree2::Template do @template=Agree2::Template.new(@user,{:permalink=>'hello'}) @fields={:amount=>100} @bob={:first_name=>'Bob',:last_name=>'Green',:email=>'bob@green.inv'} + @json=IO.read(File.join(File.dirname(__FILE__),"fixtures","agreement.json")) + end it "should have a user" do @@ -38,7 +40,7 @@ describe Agree2::Template do end it "should call raw_prepare with correct parameters" do - @user.should_receive(:post).with("/masters/hello/prepare",:fields=>@fields,:parties=>{:client=>@bob}) + @user.should_receive(:post).with("/masters/hello/prepare",:fields=>@fields,:parties=>{:client=>@bob}).and_return(@json) @template.prepare(@fields,{:client=>@bob}) end @@ -68,7 +70,7 @@ describe Agree2::Template do it "should call raw_prepare with correct parameters" do @user.should_receive(:post).with("/masters/hello/prepare",:fields=>@fields, - :parties=>{:client=>@bob,'application'=>:application},:sign=>'application') + :parties=>{:client=>@bob,'application'=>:application},:sign=>'application').and_return(@json) @template.prepare_and_sign(@fields,{:client=>@bob}) end spec/template_spec.rb @@ -41,19 +41,19 @@ describe Agree2::User do [:get,:head,:delete].each do |m| it "should perform http #{m.to_s}" do - @token.should_receive(m).with("/test").and_return(@response) + @token.should_receive(m).with("/test",{'Content-Type'=>'application/json','Accept'=>'application/json'}).and_return(@response) @user.send(m,"/test").should==@json end end [:post,:put].each do |m| it "should perform http #{m.to_s} with no data" do - @token.should_receive(m).with("/test",nil,{'Content-Type'=>'application/json'}).and_return(@response) + @token.should_receive(m).with("/test",nil,{'Content-Type'=>'application/json','Accept'=>'application/json'}).and_return(@response) @user.send(m,"/test").should==@json end it "should perform http #{m.to_s} with hash" do - @token.should_receive(m).with("/test",'{"test":"this"}',{'Content-Type'=>'application/json'}).and_return(@response) + @token.should_receive(m).with("/test",'{"test":"this"}',{'Content-Type'=>'application/json','Accept'=>'application/json'}).and_return(@response) @user.send(m,"/test",{:test=>'this'}).should==@json end end spec/user_spec.rb ab2e56650e5163339c076a5d9e615e19a3714179 Pelle Braendgaard pelleb@gmail.com http://github.com/pelle/agree2-client/commit/ac2ba29a5c8037f59c6951b05c42cfa09a00f684 ac2ba29a5c8037f59c6951b05c42cfa09a00f684 2008-08-25T02:48:42-07:00 2008-08-25T02:48:42-07:00 Improved build structure. Full crud support for individual objects as well as proxy collections 84fd799c18098c90282e234ce2865b975c6c3d29 Pelle Braendgaard pelleb@gmail.com