tsenart-pivotal-tracker 0.4.0

data/Gemfile

@@ -0,0 +1,16 @@
+source 'http://rubygems.org'
+
+group :runtime do
+  gem 'rest-client', '~> 1.6.0'
+  gem 'happymapper', '>= 0.3.2'
+  gem 'builder'
+  gem 'nokogiri', '~> 1.4'
+end
+
+group :test do
+  gem 'rspec', '~> 1.3.0', :require => 'spec'
+  gem 'rake'
+  gem 'jeweler'
+  gem 'stale_fish', '~> 1.3.0'
+  gem "ruby-debug"
+end

data/Gemfile.lock

@@ -0,0 +1,48 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (2.3.8)
+    builder (2.1.2)
+    columnize (0.3.2)
+    fakeweb (1.2.8)
+    gemcutter (0.6.1)
+    git (1.2.5)
+    happymapper (0.3.2)
+      libxml-ruby (~> 1.1.3)
+    jeweler (1.4.0)
+      gemcutter (>= 0.1.0)
+      git (>= 1.2.5)
+      rubyforge (>= 2.0.0)
+    json_pure (1.4.5)
+    libxml-ruby (1.1.4)
+    linecache (0.43)
+    mime-types (1.16)
+    nokogiri (1.4.4)
+    rake (0.8.7)
+    rest-client (1.6.0)
+      mime-types (>= 1.16)
+    rspec (1.3.2)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    stale_fish (1.3.0)
+      activesupport
+      fakeweb
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  builder
+  happymapper (>= 0.3.2)
+  jeweler
+  nokogiri (~> 1.4)
+  rake
+  rest-client (~> 1.6.0)
+  rspec (~> 1.3.0)
+  ruby-debug
+  stale_fish (~> 1.3.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Justin Smestad
+
+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,77 @@
+= pivotal-tracker.rb
+
+Ruby wrapper for Pivotal Tracker API, no frameworks required. Simply Ruby.
+
+== Features
+
+* Compatible with Pivotal Tracker API version 3
+* ActiveRecord-style Wrapper API
+* Support for SSL protected repositories
+
+== Overview
+
+    PivotalTracker::Client.token('myusername@email.com', 'secretpassword')        # Automatically fetch API Token
+    PivotalTracker::Client.token = 'jkfduisj97823974j2kl24899234'                 # Manually set API Token
+
+    @projects = PivotalTracker::Project.all                                       # return all projects
+    @a_project = PivotalTracker::Project.find(84739)                              # find project with a given ID
+
+    @a_project.stories.all                                                        # return all stories for "a_project"
+    @a_project.stories.all(:label => 'overdue', :story_type => ['bug', 'chore'])  # return all stories that match the passed filters
+    @a_project.stories.find(847762630)                                            # find story with a given ID
+
+    @a_project.stories.create(:name => 'My Story', :story_type => 'feature')      # create a story for this project
+
+    # all tracker defined filters are allowed, as well as :limit & :offset for pagination
+
+    # The below pattern below is planned to be added to the final release:
+
+    @a_project.stories << PivotalTracker::Story.new(84739, :name => 'Ur Story')   # same as earlier story creation, useful for copying/cloning from proj
+
+
+    @story = @a_project.stories.find(847762630)
+    @story.notes.all                                                              # return all notes (comments) for a story
+    @story.notes.create(:text => 'A new comment', :noted_at => '06/29/2010 05:00 EST')  # add a new note
+
+
+    @story.attachments                                                            # return an array of all attachment items (data only, not the files)
+    @story.upload_attachment(file_path)                                           # add a file attachment to @story that can be found at file_path
+
+
+    # All 4 examples below return a PivotalTracker::Story from the new project, with the same story ID
+
+    @story.move_to_project(123456)                                                # move @story to the project with ID 123456
+    @story.move_to_project('123456')                                              # same as above
+    @story.move_to_project(@project)                                              # move @story to @project
+    @story.move_to_project(@another_story)                                        # move @story into the same project as @another_story
+
+
+
+The API is based on the following this gist: http://gist.github.com/283120
+
+== Getting Started
+
+* Installing:
+
+    $ gem install pivotal-tracker
+
+* Contributing (requires Bundler >= 0.9.7):
+
+    $ git clone git://github.com/jsmestad/pivotal-tracker
+    $ cd pivotal-tracker
+    $ bundle install
+    $ bundle exec rake
+
+== Additional Information
+
+* Wiki: http://wiki.github.com/jsmestad/pivotal-tracker
+* Documentation: http://rdoc.info/projects/jsmestad/pivotal-tracker
+* Pivotal API v3 Docs: http://www.pivotaltracker.com/help/api?version=v3
+
+== Contributors along the way
+
+* Justin Smestad (http://github.com/jsmestad)
+* Josh Nichols (http://github.com/technicalpickles)
+* Terence Lee (http://github.com/hone)
+* Jon Mischo (http://github.com/supertaz)
+* Gabor Ratky (http://github.com/rgabo)

data/Rakefile

@@ -0,0 +1,50 @@
+# encoding: utf-8
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "tsenart-pivotal-tracker"
+    gem.summary = %Q{Ruby wrapper for the Pivotal Tracker API}
+    gem.email = "justin.smestad@gmail.com"
+    gem.homepage = "http://github.com/tsenart/pivotal-tracker"
+    gem.authors = ["Justin Smestad", "Josh Nichols", "Terence Lee", "Tomás Senart"]
+
+    gem.add_dependency 'rest-client', '~> 1.6.0'
+    gem.add_dependency 'happymapper', '>= 0.3.2'
+    gem.add_dependency 'builder'
+    gem.add_dependency 'nokogiri', '~> 1.4.3.1'
+
+    gem.add_development_dependency 'rspec'
+    gem.add_development_dependency 'bundler', '>= 0.9.26'
+    gem.add_development_dependency 'jeweler'
+    gem.add_development_dependency 'stale_fish', '~> 1.3.0'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.4.0

data/lib/pivotal-tracker/activity.rb

@@ -0,0 +1,46 @@
+module PivotalTracker
+  class Activity
+    include HappyMapper
+    class << self
+      def all(project=nil, options={})
+        params = self.encode_options(options)
+        if project
+          parse(Client.connection["/projects/#{project.id}/activities#{params}"].get)
+        else
+          parse(Client.connection["/activities#{params}"].get)
+        end
+      end
+
+      protected
+
+        def encode_options(options)
+          return nil if !options.is_a?(Hash) || options.empty?
+
+          options_string = []
+          options_string << "limit=#{options.delete(:limit)}" if options[:limit]
+          options_string << "newer_than_version=#{options.delete(:newer_than_version)}" if options[:newer_than_version]
+
+          if options[:occurred_since]
+            options_string << "occurred_since_date=\"#{options[:occurred_since].utc}\""
+          elsif options[:occurred_since_date]
+            #NOTE currently forces UTC as the timezone
+            options_string << "occurred_since_date=#{URI.escape options[:occurred_since_date].strftime("%Y/%m/%d %H:%M:%S UTC")}"
+          end
+
+          return "?#{options_string.join('&')}"
+        end
+
+    end
+
+    element :id, Integer
+    element :version, Integer
+    element :event_type, String
+    element :occurred_at, DateTime
+    element :author, String
+    element :project_id, Integer
+    element :description, String
+
+    has_many :stories, Story
+
+  end
+end

data/lib/pivotal-tracker/attachment.rb

@@ -0,0 +1,16 @@
+module PivotalTracker
+  class Attachment
+    include HappyMapper
+
+    tag 'attachment'
+
+    element :id, Integer
+    element :filename, String
+    element :description, String
+    element :uploaded_by, String
+    element :uploaded_at, DateTime
+    element :url, String
+    element :status, String
+
+  end
+end

data/lib/pivotal-tracker/client.rb

@@ -0,0 +1,41 @@
+module PivotalTracker
+  class Client
+
+    class NoToken < StandardError; end
+
+    class << self
+      attr_writer :use_ssl, :token
+
+      def use_ssl
+        @use_ssl || false
+      end
+
+      def token(username, password, method='post')
+        return @token if @token
+        response = if method == 'post'
+          RestClient.post 'https://www.pivotaltracker.com/services/v3/tokens/active', :username => username, :password => password
+        else
+          RestClient.get "https://#{username}:#{password}@www.pivotaltracker.com/services/v3/tokens/active"
+        end
+        @token= Nokogiri::XML(response.body).search('guid').inner_html
+      end
+
+      # this is your connection for the entire module
+      def connection(options={})
+        raise NoToken if @token.to_s.empty?
+
+        @connections ||= {}
+
+        @connections[@token] ||= RestClient::Resource.new("#{protocol}://www.pivotaltracker.com/services/v3", :headers => {'X-TrackerToken' => @token, 'Content-Type' => 'application/xml'})
+      end
+
+      protected
+
+        def protocol
+          use_ssl ? 'https' : 'http'
+        end
+
+    end
+
+  end
+end

data/lib/pivotal-tracker/extensions.rb

@@ -0,0 +1,11 @@
+# Happymapper patch for RestClient API Change (response => response.body)
+
+module HappyMapper
+  module ClassMethods
+    alias_method :orig_parse, :parse
+    def parse(xml, options={})
+      xml = xml.to_s if xml.is_a?(RestClient::Response)
+      orig_parse(xml, options)
+    end
+  end
+end

data/lib/pivotal-tracker/iteration.rb

@@ -0,0 +1,34 @@
+module PivotalTracker
+  class Iteration
+    include HappyMapper
+
+    class << self
+      def all(project, options={})
+        params = PivotalTracker.encode_options(options)
+        parse(Client.connection["/projects/#{project.id}/iterations#{params}"].get)
+      end
+      
+      def current(project)
+        array = parse(Client.connection["projects/#{project.id}/iterations/current"].get)
+        array.first if array
+      end
+
+      def done(project, options={})
+        params = PivotalTracker.encode_options(options)
+        parse(Client.connection["/projects/#{project.id}/iterations/done#{params}"].get)
+      end
+
+      def backlog(project, options={})
+        params = PivotalTracker.encode_options(options)
+        parse(Client.connection["/projects/#{project.id}/iterations/backlog#{params}"].get)
+      end
+    end
+
+    element :id, Integer
+    element :number, Integer
+    element :start, DateTime
+    element :finish, DateTime
+    has_many :stories, Story
+
+  end
+end

data/lib/pivotal-tracker/membership.rb

@@ -0,0 +1,20 @@
+module PivotalTracker
+  class Membership
+    include HappyMapper
+
+    class << self
+      def all(project, options={})
+        parse(Client.connection["/projects/#{project.id}/memberships"].get)
+      end
+    end
+
+    element :id, Integer
+    element :role, String
+
+    # Flattened Attributes from <person>...</person>
+    element :name, String, :deep => true
+    element :email, String, :deep => true
+    element :initials, String, :deep => true
+
+  end
+end

data/lib/pivotal-tracker/note.rb

@@ -0,0 +1,58 @@
+module PivotalTracker
+  class Note
+    include HappyMapper
+
+    class << self
+      def all(story, options={})
+        notes = parse(Client.connection["/projects/#{story.project_id}/stories/#{story.id}/notes"].get)
+        notes.each { |n| n.project_id, n.story_id = story.project_id, story.id }
+        return notes
+      end
+    end
+
+    attr_accessor :project_id, :story_id
+
+    element :id, Integer
+    element :text, String
+    element :author, String
+    element :noted_at, DateTime
+    has_one :story, Story
+
+    def initialize(attributes={})
+      if attributes[:owner]
+        self.story = attributes.delete(:owner) 
+        self.project_id = self.story.project_id
+        self.story_id = self.story.id
+      end
+
+      update_attributes(attributes)
+    end
+    
+    def create
+      response = Client.connection["/projects/#{project_id}/stories/#{story_id}/notes"].post(self.to_xml, :content_type => 'application/xml')
+      return Note.parse(response)
+    end
+
+    # Pivotal Tracker API doesn't seem to support updating or deleting notes at this time.
+
+    protected
+
+      def to_xml
+        builder = Nokogiri::XML::Builder.new do |xml|
+          xml.note {
+            #xml.author "#{author}"
+            xml.text_ "#{text}"
+            xml.noted_at "#{noted_at}"
+          }
+        end
+        return builder.to_xml
+      end
+
+      def update_attributes(attrs)
+        attrs.each do |key, value|
+          self.send("#{key}=", value.is_a?(Array) ? value.join(',') : value )
+        end
+      end
+      
+  end
+end

data/lib/pivotal-tracker/project.rb

@@ -0,0 +1,58 @@
+module PivotalTracker
+  class Project
+    include HappyMapper
+
+    class << self
+      def all
+        @found = parse(Client.connection['/projects'].get)
+      end
+
+      def find(id)
+        if @found
+          @found.detect { |document| document.id == id }
+        else
+          parse(Client.connection["/projects/#{id}"].get)
+        end
+      end
+    end
+
+    element :id, Integer
+    element :name, String
+    element :account, String
+    element :week_start_day, String
+    element :point_scale, String
+    element :week_start_day, String
+    element :velocity_scheme, String
+    element :iteration_length, Integer
+    element :initial_velocity, Integer
+    element :current_velocity, Integer
+    element :last_activity_at, DateTime
+    element :use_https, Boolean
+
+    def activities
+      @activities ||= Proxy.new(self, Activity)
+    end
+
+    def iterations
+      @iterations ||= Proxy.new(self, Iteration)
+    end
+
+    def stories
+      @stories ||= Proxy.new(self, Story)
+    end
+
+    def memberships
+      @memberships ||= Proxy.new(self, Membership)
+    end
+
+    def iteration(group)
+      case group.to_sym
+      when :done then Iteration.done(self)
+      when :current then Iteration.current(self)
+      when :backlog then Iteration.backlog(self)
+      else
+        raise ArgumentError, "Invalid group. Use :done, :current or :backlog instead."
+      end
+    end
+  end
+end

data/lib/pivotal-tracker/proxy.rb

@@ -0,0 +1,66 @@
+class BasicObject #:nodoc:
+  instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|^send$|instance_eval|proxy_|^object_id$)/ }
+end unless defined?(BasicObject)
+
+module PivotalTracker
+  class Proxy < BasicObject
+
+    def initialize(owner, target)
+      @owner = owner
+      @target = target
+      @opts = nil
+    end
+
+    def all(options={})
+      proxy_found(options)
+    end
+
+    def find(param, options={})
+      return all(options) if param == :all
+      return @target.find(param, @owner.id) if @target.respond_to?("find")
+      return proxy_found(options).detect { |document| document.id == param }
+    end
+
+    def <<(*objects)
+      objects.flatten.each do |object|
+        if obj = object.create
+          return obj
+        else
+          return object
+        end
+      end
+    end
+
+    def create(args)
+      object = @target.new(args.merge({:owner => @owner}))
+      if obj = object.create
+        return obj
+      else
+        return object
+      end
+    end
+
+    protected
+
+      def proxy_found(options)
+        # Check to see if options have changed
+        if @opts == options
+          @found ||= load_found(options)
+        else
+          load_found(options)
+        end
+      end
+
+    private
+
+      def method_missing(method, *args, &block)
+        @target.send(method, *args, &block)
+      end
+
+      def load_found(options)
+        @opts = options
+        @target.all(@owner, @opts)
+      end
+
+  end
+end