pivotal_tracker 0.1.0 → 0.2.0

data/README.rdoc

@@ -1,12 +1,46 @@
 = pivotal_tracker
 
-This is a simple ruby wrapper for the Pivotal Tracker API.
+This is a simple ruby wrapper for the Pivotal Tracker V2 API utilizing HTTParty and Crack::XML.
+
+== Setup
+
+Make sure you have gemcutter
+  sudo gem install gemcutter
+  gem tumble
+  
+Install the gem
+  sudo gem install pivotal_tracker
+
+== Usage
+
+Create a PivotalTracker object with your API key:
+  tracker = PivotalTracker.new('API_KEY')
+  
+Use any of the currently implemented methods and access them like access the resources returned.
+Notice that all data returned is parsed and built into Mash objects/arrays for you:
+  projects = tracker.get_all_projects
+  projects.first.memberships.first.person.name
+  => "Joslyn Esser"
+  
+== Currently implemented methods (More to come!)
+
+* get_all_activities 
+* get_all_project_activities(project_id)
+* get_all_projects
+* get_project(project_id)
+* create_project(name, options = {})
+* get_all_project_memberships(project_id)
+* get_project_membership(project_id, membership_id)
+* add_project_membership(project_id, role, email, options = {})
+* remove_project_membership(project_id, membership_id)
+* get_all_project_iterations(project_id)
+* get_all_project_stories(project_id)
 
 == Note on Patches/Pull Requests
  
 * Fork the project.
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
+* Add specs for it. This is important so I don't break it in a
   future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
   (if you want to have your own version, that is fine but

data/Rakefile

@@ -5,7 +5,7 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "pivotal_tracker"
-    gem.summary = %Q{Simple ruby wrapper for the Pivotal Tracker API}
+    gem.summary = %Q{Ruby wrapper for the Pivotal Tracker V2 API utilizing HTTParty and Crack XML parsing}
     gem.email = "joslyn.esser@gmail.com"
     gem.homepage = "http://github.com/joslynesser/pivotal_tracker"
     gem.authors = ["Joslyn Esser"]
@@ -14,6 +14,7 @@ begin
     gem.add_development_dependency "fakeweb", ">= 1.2.7"
     
     gem.add_dependency "httparty", ">= 0.4.5"
+    gem.add_dependency "mash", ">= 0.0.3"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/pivotal_tracker/error.rb

@@ -0,0 +1,16 @@
+class PivotalTracker::Error < StandardError
+  attr_reader :data
+  
+  def initialize(data)
+    @data = data
+    super
+  end
+end
+
+class PivotalTracker::BadRequest        < PivotalTracker::Error; end
+class PivotalTracker::Unauthorized      < PivotalTracker::Error; end
+
+class PivotalTracker::General           < StandardError; end
+class PivotalTracker::Unavailable       < StandardError; end
+class PivotalTracker::InformPivotal     < StandardError; end
+class PivotalTracker::ResourceNotFound  < StandardError; end

data/lib/pivotal_tracker.rb

@@ -1,7 +1,9 @@
 require 'rubygems'
 require 'httparty'
+require 'mash'
 
 class PivotalTracker
+  
   include HTTParty
   base_uri 'www.pivotaltracker.com/services/v2'
   format :xml
@@ -10,20 +12,110 @@ class PivotalTracker
     self.class.headers 'X-TrackerToken' => api_token
   end
   
+  def get_all_activities
+    response = self.class.get("/activities")
+    raise_errors(response)
+    parse_response(response, 'activities')
+  end
+  
+  def get_all_project_activities(project_id)
+    response = self.class.get("/projects/#{project_id}/activities")
+    raise_errors(response)
+    parse_response(response, 'activities')
+  end
+  
+  def get_all_projects
+    response = self.class.get("/projects")
+    raise_errors(response)
+    parse_response(response, 'projects')
+  end
+  
+  def get_project(project_id)
+    response = self.class.get("/projects/#{project_id}")
+    raise_errors(response)
+    parse_response(response, 'project')
+  end
+  
   def create_project(name, options = {})
-    data = self.class.post('/projects/', :body => {:project => options.merge(:name => name)})
-    project = PivotalTracker::Project.new(data['project'])
+    response = self.class.post('/projects', :body => {:project => options.merge(:name => name)})
+    raise_errors(response)
+    parse_response(response, 'project')
   end
   
-  def add_member_to_project(project_id, role, email, person_options = {})
-    data = self.class.post("/projects/#{project_id}/memberships/", :body => {:membership => {:role => role, :person => person_options.merge(:email => email)}})
-    membership = PivotalTracker::Membership.new(data['membership'])
+  def get_all_project_memberships(project_id)
+    response = self.class.get("/projects/#{project_id}/memberships")
+    raise_errors(response)
+    parse_response(response, 'memberships')
   end
   
-  def remove_member_from_project(project_id, membership_id)
-    data = self.class.delete("/projects/#{project_id}/memberships/#{membership_id}/")
-    membership = PivotalTracker::Membership.new(data['membership']) if data['membership']
+  def get_project_membership(project_id, membership_id)
+    response = self.class.get("/projects/#{project_id}/memberships/#{membership_id}")
+    raise_errors(response)
+    parse_response(response, 'membership')
   end
+  
+  def add_project_membership(project_id, role, email, options = {})
+    response = self.class.post("/projects/#{project_id}/memberships", :body => {:membership => {:role => role, :person => options.merge(:email => email)}})
+    raise_errors(response)
+    parse_response(response, 'membership')
+  end
+  
+  def remove_project_membership(project_id, membership_id)
+    response = self.class.delete("/projects/#{project_id}/memberships/#{membership_id}")
+    raise_errors(response)
+    parse_response(response, 'membership')
+  end
+  
+  def get_all_project_iterations(project_id)
+    response = self.class.get("/projects/#{project_id}/iterations")
+    raise_errors(response)
+    parse_response(response, 'iterations')
+  end
+  
+  def get_all_project_stories(project_id)
+    response = self.class.get("/projects/#{project_id}/stories")
+    raise_errors(response)
+    parse_response(response, 'stories')
+  end
+    
+  private
+  
+    def raise_errors(response)
+      case response.code.to_i
+        when 400
+          raise PivotalTracker::BadRequest.new(response), "(#{response.code}): #{response.message} - #{response['message'] if response}"
+        when 401
+          raise PivotalTracker::Unauthorized.new(response), "(#{response.code}): #{response.message} - #{response.body if response}"
+        when 403
+          raise PivotalTracker::General, "(#{response.code}): #{response.message}"
+        when 404
+          raise PivotalTracker::ResourceNotFound, "(#{response.code}): #{response.message}"
+        when 500
+          raise PivotalTracker::InformPivotal, "Pivotal Tracker had an internal error. Please let them know. (#{response.code}): #{response.message}"
+        when 502..503
+          raise PivotalTracker::Unavailable, "(#{response.code}): #{response.message}"
+      end
+    end
+    
+    # Create Mash objects from response data for the given resource(s)
+    def parse_response(response, resource)
+      response = cleanup_pivotal_data(response.body)
+      data = response[resource]
+      if data.is_a?(Array)
+        data.collect {|object| Mash.new(object)}
+      else
+        Mash.new(data)
+      end
+    end
+    
+    # Make Crack's XML parsing happy by correctly defining Pivotal's nested collections as arrays
+    # This can be removed when all collections returned by Pivotal Tracker's API have the type=array attribute set
+    def cleanup_pivotal_data(body)
+      %w{ projects memberships iterations stories }.each do |resource|
+        body.gsub!("<#{resource}>", "<#{resource} type=\"array\">")
+      end
+      response = Crack::XML.parse(body)
+    end
 end
 
-require File.dirname(__FILE__) + '/pivotal_tracker/data'
+require File.dirname(__FILE__) + '/pivotal_tracker/error'

data/pivotal_tracker.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{pivotal_tracker}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joslyn Esser"]
-  s.date = %q{2009-11-05}
+  s.date = %q{2009-11-06}
   s.email = %q{joslyn.esser@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -23,10 +23,16 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "lib/pivotal_tracker.rb",
-     "lib/pivotal_tracker/data.rb",
+     "lib/pivotal_tracker/error.rb",
      "pivotal_tracker.gemspec",
+     "spec/fixtures/activities.xml",
+     "spec/fixtures/iterations.xml",
      "spec/fixtures/membership.xml",
+     "spec/fixtures/memberships.xml",
      "spec/fixtures/project.xml",
+     "spec/fixtures/projects.xml",
+     "spec/fixtures/stories.xml",
+     "spec/fixtures/story.xml",
      "spec/pivotal_tracker_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb"
@@ -35,7 +41,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Simple ruby wrapper for the Pivotal Tracker API}
+  s.summary = %q{Ruby wrapper for the Pivotal Tracker V2 API utilizing HTTParty and Crack XML parsing}
   s.test_files = [
     "spec/pivotal_tracker_spec.rb",
      "spec/spec_helper.rb"
@@ -49,15 +55,18 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<fakeweb>, [">= 1.2.7"])
       s.add_runtime_dependency(%q<httparty>, [">= 0.4.5"])
+      s.add_runtime_dependency(%q<mash>, [">= 0.0.3"])
     else
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<fakeweb>, [">= 1.2.7"])
       s.add_dependency(%q<httparty>, [">= 0.4.5"])
+      s.add_dependency(%q<mash>, [">= 0.0.3"])
     end
   else
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<fakeweb>, [">= 1.2.7"])
     s.add_dependency(%q<httparty>, [">= 0.4.5"])
+    s.add_dependency(%q<mash>, [">= 0.0.3"])
   end
 end
 

data/spec/fixtures/activities.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<activities type="array">
+  <activity>
+    <id type="integer">1031</id>
+    <project>Sample Project</project>
+    <story>More power to shields</story>
+    <description>James Kirk accepted &quot;More power to shields&quot;</description>
+    <author>James Kirk </author>
+    <when>06/01/2009 08:22 AM</when>
+  </activity>
+  <activity>
+    <id type="integer">1030</id>
+    <project>Another Sample Project</project>
+    <story>Warp speed</story>
+    <description>Montgomery Scott rejected &quot;Warp speend&quot; with comments: &quot;Warp speed isn't working&quot;</description>
+    <author>Montgomery Scott</author>
+    <when>06/01/2009 12:22 AM</when>
+  </activity>
+</activities>

data/spec/fixtures/iterations.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<iterations type="array">
+  <iteration>
+    <id type="integer">1</id>
+    <number type="integer">1</number>
+    <start type="datetime">2009/03/16 00:00:00 UTC</start>
+    <finish type="datetime">2009/03/23 00:00:00 UTC</finish>
+    <stories>
+      <story>
+        <id type="integer">1</id>
+        <story_type>feature</story_type>
+        <url>STORY_URL</url>
+        <estimate type="integer">2</estimate>
+        <current_state>accepted</current_state>
+        <description>Windoze Save Dialog thingy</description>
+        <name>The Save Dialog</name>
+        <requested_by>Dana Deer</requested_by>
+        <owned_by>Rob</owned_by>
+        <created_at type="datetime">2009/03/16 16:55:04 UTC</created_at>
+        <accepted_at type="datetime">2009/03/19 19:00:00 UTC</accepted_at>
+      </story>
+    </stories>
+  </iteration>
+</iterations>

data/spec/fixtures/memberships.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<memberships type="array">
+  <membership>
+    <id>1</id>
+    <person>
+      <email>picard@earth.ufp</email>
+      <name>Jean-Luc Picard</name>
+      <initials>jlp</initials>
+    </person>
+    <role>Owner</role>
+    <project>
+      <id>1</id>
+      <name>Warp Engine Upgrades</name>
+    </project>
+  </membership>
+  <membership>
+    <id>2</id>
+    <person>
+      <email>jadzia@trill.ufp</email>
+      <name>Jadzia Dax</name>
+      <initials>JD</initials>
+    </person>
+    <role>Member</role>
+    <project>
+      <id>1</id>
+      <name>Warp Engine Upgrades</name>
+    </project>
+  </membership>
+</memberships>

data/spec/fixtures/projects.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projects type="array">
+  <project>
+    <id>1</id>
+    <name>Sample Project</name>
+    <iteration_length type="integer">2</iteration_length>
+    <week_start_day>Monday</week_start_day>
+    <point_scale>0,1,2,3</point_scale>
+    <velocity_scheme>Average of 4 iterations</velocity_scheme>
+    <initial_velocity>10</initial_velocity>
+    <number_of_done_iterations_to_show>12</number_of_done_iterations_to_show>
+    <allow_attachments>true</allow_attachments>
+    <public>false</public>
+    <use_https>true</use_https>
+    <bugs_and_chores_are_estimatable>false</bugs_and_chores_are_estimatable>
+    <commit_mode>false</commit_mode>
+    <memberships>
+      <membership>
+        <id>1006</id>
+        <person>
+          <email>kirkybaby@earth.ufp</email>
+          <name>James T. Kirk</name>
+          <initials>JTK</initials>
+        </person>
+        <role>Owner</role>
+      </membership>
+    </memberships>
+  </project>
+  <project>
+    <id>2</id>
+    <name>Sample Project 2</name>
+    <iteration_length type="integer">4</iteration_length>
+    <week_start_day>Monday</week_start_day>
+    <point_scale>0,1,2,3</point_scale>
+    <velocity_scheme>Average of 4 iterations</velocity_scheme>
+    <initial_velocity>10</initial_velocity>
+    <number_of_done_iterations_to_show>12</number_of_done_iterations_to_show>
+    <allow_attachments>false</allow_attachments>
+    <public>true</public>
+    <use_https>false</use_https>
+    <bugs_and_chores_are_estimatable>false</bugs_and_chores_are_estimatable>
+    <commit_mode>false</commit_mode>
+    <memberships>
+    </memberships>
+  </project>
+</projects>

data/spec/fixtures/stories.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<stories type="array" count="10" total="10">
+  <story>
+    <id type="integer">STORY_ID</id>
+    <story_type>feature</story_type>
+    <url>http://www.pivotaltracker.com/story/show/STORY_ID</url>
+    <estimate type="integer">1</estimate>
+    <current_state>accepted</current_state>
+    <description></description>
+    <name>More power to shields</name>
+    <requested_by>James Kirk</requested_by>
+    <owned_by>Montgomery Scott</owned_by>
+    <created_at type="datetime">2008/12/10 00:00:00 UTC</created_at>
+    <accepted_at type="datetime">2008/12/10 00:00:00 UTC</accepted_at>
+    <labels>label 1,label 2,label 3</labels>
+  </story>
+</stories>

data/spec/fixtures/story.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<story>
+  <id type="integer">2751</id>
+  <story_type>feature</story_type>
+  <url>http://www.pivotaltracker.com/story/show/2751</url>
+  <estimate type="integer">-1</estimate>
+  <current_state>unscheduled</current_state>
+  <description></description>
+  <name>Fire torpedoes</name>
+  <requested_by>James Kirk</requested_by>
+  <created_at type="datetime">2008/12/10 00:00:00 UTC</created_at>
+</story>

data/spec/pivotal_tracker_spec.rb

@@ -1,6 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-describe "PivotalTracker" do
+describe PivotalTracker do
   
   describe "Initialization" do
     it "should require an API token" do
@@ -13,52 +13,111 @@ describe "PivotalTracker" do
     end
   end
   
-  describe "Data" do
+  describe "API" do
     before(:each) do
-      @data = PivotalTracker::Data.new({'foo' => 'bar'})
+      @tracker = PivotalTracker.new('12345')      
     end
-    
-    it "should resemble a nested OpenStruct" do
-      @data.foo.should == 'bar'
+
+    describe "Activities" do
+      it "should get all recent activities" do
+        stub_get('/activities', 'activities.xml')
+        activities = @tracker.get_all_activities
+        activities.first.description.should == "James Kirk accepted \"More power to shields\""
+      end
+      
+      it "should get all recent activities for a given project" do
+        stub_get('/projects/1/activities', 'activities.xml')
+        activities = @tracker.get_all_project_activities(1)
+        activities.first.description.should == "James Kirk accepted \"More power to shields\""
+      end
     end
     
-    it "should return nil for missing keys" do
-      @data.foobar.should be_nil
+    describe "Projects" do
+      it "should get all projects" do
+        stub_get('/projects', 'projects.xml')
+        projects = @tracker.get_all_projects
+        projects.first.name.should == 'Sample Project'
+        projects.first.memberships.first.person.name.should == 'James T. Kirk'
+      end
+      
+      it "should get a project" do
+        stub_get("/projects/27", 'project.xml')
+        project = @tracker.get_project(27)
+        project.name.should == 'Cardassian War Plans'
+      end
+      
+      it "should create a project" do
+        stub_post('/projects', 'project.xml')
+        project = @tracker.create_project('Cardassian War Plans')
+        project.name.should == 'Cardassian War Plans'
+      end
     end
-  end
   
-  describe "Projects" do
-    before(:each) do
-      @tracker = PivotalTracker.new('12345')
-    end
+    describe "Memberships" do
+      it "should get all memberships for a given project" do
+        stub_get('/projects/1/memberships', 'memberships.xml')
+        memberships = @tracker.get_all_project_memberships(1)
+        memberships.first.person.name.should == 'Jean-Luc Picard'
+      end
+      
+      it "should get a single membership for a given project" do
+        stub_get('/projects/1/memberships/15007', 'membership.xml')
+        membership = @tracker.get_project_membership(1, 15007)
+        membership.person.name.should == 'Jadzia Dax'
+      end
+      
+      it "should add memberships to a given project" do
+        stub_post('/projects/12345/memberships', 'membership.xml')
+        membership = @tracker.add_project_membership(12345, 'Member', 'jadzia@trill.ufp')
+        membership.person.name.should == 'Jadzia Dax'
+      end
     
-    it "should create projects" do
-      stub_post('/projects/', 'project.xml')
-      project = @tracker.create_project('Cardassian War Plans')
-      project.name.should == 'Cardassian War Plans'
-    end
-  end
-  
-  describe "Memberships" do
-    before(:each) do
-      @tracker = PivotalTracker.new('12345')
+      it "should remove memberships from a given project" do
+        stub_delete('/projects/12345/memberships/15007', 'membership.xml')
+        membership = @tracker.remove_project_membership(12345, 15007)
+        membership.person.name.should == 'Jadzia Dax'
+      end
     end
     
-    it "should add members to a given project" do
-      stub_post('/projects/12345/memberships/', 'membership.xml')
-      membership = @tracker.add_member_to_project(12345, 'Member', 'jadzia@trill.ufp')
-      membership.person.name.should == 'Jadzia Dax'
+    describe "Iterations" do
+      it "should get all iterations for a given project" do
+        stub_get('/projects/1/iterations', 'iterations.xml')
+        iterations = @tracker.get_all_project_iterations(1)
+        iterations.first.stories.first.story_type.should == 'feature'
+      end
+      
+      it "should get iterations filtered by done, current, or backlog" do
+        pending
+      end
+      
+      it "should get iterations by limit and offset" do
+        pending
+      end
     end
     
-    it "should remove members from a given project" do
-      stub_delete('/projects/12345/memberships/15007/', 'membership.xml')
-      membership = @tracker.remove_member_from_project(12345, 15007)
-      membership.person.name.should == 'Jadzia Dax'
+    describe "Stories" do
+      it "should get all stories for a given project" do
+        stub_get('/projects/1/stories', 'stories.xml')
+        stories = @tracker.get_all_project_stories(1)
+        stories.first.owned_by.should == 'Montgomery Scott'
+      end
+      
+      it "should get all stories for a project based on a given filter" do
+        pending
+      end
+      
+      it "should get all stories for a project paginated by a limit and offset" do
+        pending
+      end
+      
+      it "should create a new story for a given project" do
+        pending
+      end
     end
   end
   
   describe "Error Handling" do
-    it "should be handled" do
+    it "should be spec'd" do
       pending
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: pivotal_tracker
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Joslyn Esser
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-05 00:00:00 -08:00
+date: 2009-11-06 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,6 +42,16 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.4.5
     version: 
+- !ruby/object:Gem::Dependency 
+  name: mash
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.3
+    version: 
 description: 
 email: joslyn.esser@gmail.com
 executables: []
@@ -59,10 +69,16 @@ files:
 - Rakefile
 - VERSION
 - lib/pivotal_tracker.rb
-- lib/pivotal_tracker/data.rb
+- lib/pivotal_tracker/error.rb
 - pivotal_tracker.gemspec
+- spec/fixtures/activities.xml
+- spec/fixtures/iterations.xml
 - spec/fixtures/membership.xml
+- spec/fixtures/memberships.xml
 - spec/fixtures/project.xml
+- spec/fixtures/projects.xml
+- spec/fixtures/stories.xml
+- spec/fixtures/story.xml
 - spec/pivotal_tracker_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -93,7 +109,7 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Simple ruby wrapper for the Pivotal Tracker API
+summary: Ruby wrapper for the Pivotal Tracker V2 API utilizing HTTParty and Crack XML parsing
 test_files: 
 - spec/pivotal_tracker_spec.rb
 - spec/spec_helper.rb

data/lib/pivotal_tracker/data.rb

@@ -1,18 +0,0 @@
-require 'ostruct'
-
-class PivotalTracker
-  class Data < OpenStruct
-    def initialize(data)
-      @table = {}
-      if data
-        for key, value in data
-          @table[key.to_sym] = value.instance_of?(Hash) ? Data.new(value) : value
-          new_ostruct_member(key)
-        end
-      end
-    end
-  end
-  
-  class Project < Data; end
-  class Membership < Data; end
-end