localshred-track-r 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+log/*
+*.swp
+Session.vim
+test/**.yml
+tmp/*

data/README.textile

@@ -0,0 +1,93 @@
+h1. What is Track-R?
+
+Track-R is a library that intends to extend PivotalTracker's API to a higher
+level using Ruby.
+
+h2. Installation
+
+<pre><code>
+  $ gem sources -a http://gems.github.com (you only have to do this once)
+  $ sudo gem install jfgomez86-track-r
+</code></pre>
+
+h2. Usage
+
+To use Track-R you first need to have a valid account on
+"PivotalTracker":http://www.pivotaltracker.com.  You also need to have an api
+token. To generate a token, use the "Create New Token" link on the My Profile
+page.
+
+If you don't want to generate a token, you can also use Track-R's token
+wrapper:
+
+<pre><code>
+  token = Token.new(:username => my_username, :password => my_password)
+</code></pre>
+
+And use this object to pass it to all the following methods.
+
+The next step is to require the library itself:
+
+<pre><code>
+  require 'track-r'
+</code></pre>
+
+Lastly you can fetch your project by creating a new Project instance:
+
+<pre><code>
+  my_project = Project.new(:project_id => my_project_id, :token => token)
+</code></pre>
+
+Want to see it's stories? Then running this:
+
+<pre><code>
+  my_project.stories
+</code></pre>
+
+Will do the job. But you probably want to fetch the backlog stories:
+
+<pre><code>
+  my_project.backlog
+</code></pre>
+
+There you go.
+
+Want to create a new story on that project? You have two choices:
+
+<pre><code>
+  my_project.create_story(:story_type => value, :estimate => value, :current_state => value, :description => value, :name => value, :requested_by => value, :owned_by => value, :created_at => value, :accepted_at => value, :labels)
+</code></pre>
+
+Note that most arguments are optional, but please at least specify a name
+and a description.
+
+Want to modify the story? Try this:
+
+<pre><code>
+  story = my_project.story(my_story_id)
+  story.name = "A new cool name"
+  story.story_type = "Bug"
+  story.description = "This is really cool"
+  story.save
+</code></pre>
+
+Don't like that story anymore? Delete it:
+
+<pre><code>
+  story.destroy
+</code></pre>
+
+Or
+
+<pre><code>
+  my_project.delete_story(story)
+</code></pre>
+
+Or
+
+<pre><code>
+  my_project.delete_story(story.id)
+</code></pre>
+
+I think this should get you started. Find any bugs? Please use github's Issue
+tracker.

data/Rakefile

@@ -0,0 +1,63 @@
+$:.unshift File.dirname(__FILE__)
+$:.unshift File.join(File.dirname(__FILE__), '/vendor/')
+require 'rubygems'
+require 'rake/gempackagetask'
+
+begin
+  require 'rake'
+  require 'rake/testtask'
+rescue LoadError
+  puts 'This script should only be accessed via the "rake" command.'
+  puts 'Installation: gem install rake -y'
+  exit
+end
+require 'rake/clean'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose    = true
+  t.warning    = false
+  #t.options    = '--runner=gtk2'
+end
+
+namespace :gems do
+  desc "Install gems listed in config/gems.yml"
+  task :install do
+    if !`whoami`.match(/root/)
+      print "WARNING: You should be running this as root.\n"
+      print "Do you want to continue?(y/N) "
+      opt  = STDIN.gets
+      fail "Not authorized" unless opt.match(/^y/i)
+    end
+    require 'install-gems/install-gems.rb'
+    InstallGems.new(File.join(File.dirname(__FILE__),'/config/gems.yml'))
+  end
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name         = "track-r"
+    gemspec.summary      = "A wrapper library for pivotal tracker's API"
+    gemspec.email        = "moc.liamg@68zemogfj".reverse
+    gemspec.homepage     = "http://github.com/jfgomez86/Track-R"
+    gemspec.description  = "track-r is a library that provides wrapper classes and methods for accessing PivotalTracker's public API."
+    gemspec.version      = "1.0.0"
+    gemspec.authors      = [ "Jose Felix Gomez" ]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+#Rake::GemPackageTask.new(spec) do |pkg|
+#  pkg.need_tar = true
+#end
+
+#namespace :gem do
+#  task :build => "pkg/#{spec.name}-#{spec.version}.gem" do
+#    puts "generated latest version"
+#  end
+#end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/config/config.yml

@@ -0,0 +1,4 @@
+--- 
+:site_location: http://www.pivotaltracker.com 
+:api_location: http://www.pivotaltracker.com/services/v2
+:api_token: cef78bdff8f2de14c17590e3810a281c

data/config/environment.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'hpricot'
+require 'open-uri'

data/config/gems.yml

@@ -0,0 +1,5 @@
+---
+- :name: hpricot
+- :name: thoughtbot-shoulda
+  :source: http://gems.github.com
+

data/lib/track-r.rb

@@ -0,0 +1,13 @@
+$:.unshift(File.dirname(__FILE__))
+require File.join(File.dirname(__FILE__), '/../config/environment.rb')
+require 'track-r/project'
+require 'track-r/iteration'
+require 'track-r/story'
+require 'track-r/token'
+require 'track-r/tracker'
+require 'cgi'
+require 'net/http'
+require 'timeout'
+
+# Load configuration globals
+CONFIG = YAML.load_file(File.join(File.dirname(__FILE__), '/../config/config.yml'))

data/lib/track-r/api_connector/connection.rb

@@ -0,0 +1,20 @@
+# Generic HTTP wrapper to make calls to the API
+module APIConnector
+  attr_accessor :request, :response
+  attr_reader :error_message
+  
+  def connect(options={})
+    raise(ArgumentError, "You must specify a path to connect to") if !options.include?(:path)
+    begin
+      @request = APIConnector::Request.new(options)
+      @response = @request.connect
+    rescue Timeout::Error
+      @error_message = "Connection timed out"
+    end
+  end
+  
+  def error?
+    !@error_message.nil?
+  end
+  
+end

data/lib/track-r/api_connector/request.rb

@@ -0,0 +1,31 @@
+module APIConnector
+  class Request
+    attr_reader :token, :path, :headers, :body, :connection_length, :error_message
+  
+    def initialize(options={})
+      @token = options[:token] || Token.new
+      @path = options[:path] || "/"
+      @connection_length = options[:connection_length].to_i || 15 # timeout
+      @headers = default_headers.merge! options
+    end
+  
+    def connect
+      Timeout::timeout(@connection_length) {
+        return APIConnector::Response.new(:body => open(api_url, @headers))
+      }
+    end
+  
+    def error?
+      !@error_message.nil?
+    end
+  
+    private
+  
+    def default_headers
+      {
+        "X-TrackerToken" => @token.to_s
+      }
+    end
+    
+  end
+end

data/lib/track-r/api_connector/response.rb

@@ -0,0 +1,21 @@
+# Generic HTTP wrapper to make calls to the API
+module APIConnector
+  class Response
+    attr_reader :headers, :body, :error_message
+    
+    def initialize(options={})
+      @headers = options[:headers] || nil
+      @body = options[:body] || nil
+      @error_message = options[:error_message] || nil
+    end
+    
+    def to_h
+      Hpricot(@body)
+    end
+    
+    def error?
+      @connection_error
+    end
+  
+  end
+end

data/lib/track-r/iteration.rb

@@ -0,0 +1,85 @@
+class Iteration
+  attr_reader :id, :project_id, :number, :type, :start_date, :finish_date, :stories, :limit, :offset, :token
+  
+  def self.find(options={})
+    @token = options[:token] || Token.new
+    if options.include?(:project_id)
+      @project_id = options[:project_id]
+      api_url = "#{CONFIG[:api_location]}/projects/#{@project_id}/iterations/#{options.include?(:type) ? options[:type] : ""}"
+      iterations = (Hpricot(open(api_url, {"X-TrackerToken" => @token.to_s}))/'iteration').map do |iteration|
+        Iteration.new(:iteration => iteration, :project_id => @project_id)
+      end
+    end
+  end
+  
+  def initialize(options={})
+    @token = options[:token] || Token.new
+    if options.include?(:project_id) && options.include?(:iteration_id)
+      @id         = options[:iteration_id]
+      @project_id = options[:project_id]
+      @number     = options[:number]
+      @type       = assign_type(options[:type])
+      @limit      = options[:limit]
+      @offset     = options[:offset]
+      @api_url    = build_api_url
+      @iteration  = Hpricot(open(@api_url, {"X-TrackerToken" => @token}))
+    elsif options.include?(:iteration) && options.include?(:project_id)
+      @project_id = options[:project_id]
+      @iteration  = options[:iteration]
+    else
+      raise ArgumentError, "Valid options are: :iteration (receives an Hpricot Object) + :project_id OR :project_id + :iteration_id"
+    end
+    build_iteration
+  end
+  
+  def start_date(format="%m/%d/%Y")
+    @finish_date.strftime(format)
+  end
+  
+  def finish_date(format="%m/%d/%Y")
+    @finish_date.strftime(format)
+  end
+  
+  private
+  
+    def build_iteration
+      @id                ||= @iteration.at('id').inner_html
+      @number             = @iteration.at('number').inner_html
+      @start_date         = Date.parse @iteration.at('start').inner_html
+      @finish_date        = Date.parse @iteration.at('finish').inner_html
+      @stories            = build_stories
+    end
+    
+    def build_stories
+      @stories = (@iteration/'story').map do |story|
+         Story.new(:story => story, :project_id => @id, :token => @token)
+      end
+    end
+  
+    def build_api_url
+      query_string = attributes.map { |key, value| "#{key.to_s}=#{CGI::escape(value)}" unless value.nil?}.compact.join('&')
+      url = "#{CONFIG[:api_location]}/projects/#{@project_id}/iterations/#{@type}?"+query_string
+      # if !@offset.nil? || !@limit.nil?
+      #   url += "?"
+      #   url += "offset=#{@offset.to_s}&" if !@offset.nil?
+      #   url += "limit=#{@limit.to_s}&" if !@limit.nil?
+      # end
+      # url
+    end
+    
+    def assign_type(type=nil)
+      use_type = nil
+      %w{ done current backlog }.each do |valid_type|
+        use_type = valid_type if /#{type}/i =~ valid_type
+      end
+      use_type
+    end
+    
+    def attributes
+      {
+        :limit => @limit,
+        :offset => @offset
+      }
+    end
+  
+end

data/lib/track-r/project.bak.rb

@@ -0,0 +1,102 @@
+# Container for project's attributes.
+# Receives a hash with either :project key pointing to an hpricot object or a
+# project_id and a token with which to fetch and build the project object
+class Project
+  attr_reader :name, :iteration_length, :id, :week_start_day, :point_scale,
+    :api_url, :url, :token
+
+  def initialize(options = {})
+    if options.include?(:project_id)
+      @id      = options[:project_id]
+      @token   = options[:token].to_s || CONFIG[:api_token]
+      @api_url = "#{CONFIG[:api_location]}/projects/#{@id}"
+      @url     = "#{CONFIG[:site_location]}/projects/#{@id}"
+      @project = Hpricot(open(@api_url, {"X-TrackerToken" => @token}))
+      @stories = nil
+    elsif options.include?(:project)
+      @project = options[:project]
+    else
+      raise ArgumentError, "Valid options are: :project (receives an Hpricot Object) OR :project_id + :token"
+    end
+    build_project
+  end
+
+  # Builds an array containing the project's story
+  def stories ; @stories || get_stories ; end
+
+  # Fetches a story with given id
+  def story(id)
+    Story.new(:story_id => id, :project_id => @id, :token => @token)
+  end
+
+  # Creates a story for this project. Receives a set of valid attributes.
+  # Returns a Story object
+  # TODO: Validate attributes
+  def create_story(attributes = {})
+    api_url = URI.parse("#{CONFIG[:api_location]}/projects/#{@id}/stories")
+    query_string = attributes.map { |key, value| "story[#{key}]=#{CGI::escape(value)}"}.join('&')
+    response = Net::HTTP.start(api_url.host, api_url.port) do |http|
+      http.post(api_url.path, query_string.concat("&token=#{@token}"))
+    end
+
+    story = (Hpricot(response.body)/:story)
+    Story.new(:story => story, :project_id => @id, :token => @token)
+  end
+
+  # Deletes a story given a Story object or a story_id
+  def delete_story(story)
+    if story.is_a?(Story)
+      api_url = URI.parse("#{CONFIG[:api_location]}/projects/#{@id}/stories/#{story.id}")
+    elsif story.is_a?(Integer) || story.to_i.is_a?(Integer)
+      api_url = URI.parse("#{CONFIG[:api_location]}/projects/#{@id}/stories/#{story}")
+    else
+      raise ArgumentError, "Should receive a story id or a Story object."
+    end
+    response = Net::HTTP.start(api_url.host, api_url.port) do |http|
+      http.delete(api_url.path, {"X-TrackerToken" => @token})
+    end
+    story = (Hpricot(response.body)/:story)
+    Story.new(:story => story, :project_id => @id, :token => @token)
+  end
+
+  def get_iterations(iteration_type=nil)
+    Iteration.find(:project_id => @id, :type => type)
+  end
+
+  # Gets the stories for a given iteration
+  def get_iteration_stories(iteration_type=nil)
+    get_iterations(type).stories
+  end
+
+  # Gets the current iteration's stories
+  # def current_stories
+    # get_stories_by_iteration("current")
+  # end
+
+  protected
+
+  # Builds a project given an hpricot object stored at instance variable
+  # @project
+  def build_project
+    @id               ||= @project.at('id').inner_html
+    @api_url          ||= "#{CONFIG[:api_location]}/projects/#{@id}"
+    @url              ||= "http://www.pivotaltracker.com/projects/#{@id}"
+    @name             = @project.at('name').inner_html
+    @iteration_length = @project.at('iteration_length').inner_html
+    @week_start_day   = @project.at('week_start_day').inner_html
+    @point_scale      = @project.at('point_scale').inner_html.split(',')
+  end
+
+  # Builds an array containing the project's stories
+  def get_stories
+    api_url = "#{CONFIG[:api_location]}/projects/#{@id}/stories"
+    @stories = (Hpricot(open(api_url, {"X-TrackerToken" => @token.to_s}))/:story).map {|story| Story.new(:story => story, :project_id => @id, :token => @token)}
+  end
+
+  # Builds an array containing the project's stories for a given iteration
+  # def get_stories_by_iteration(name)
+  #   api_url = "#{CONFIG[:api_location]}/projects/#{@id}/iterations/#{name}"
+  #   @stories = (Hpricot(open(api_url, {"X-TrackerToken" => @token.to_s}))/:story).map {|story| Story.new(:story => story, :project_id => @id, :token => @token)}
+  # end
+
+end # class Tracker::Project

data/lib/track-r/project.rb

@@ -0,0 +1,122 @@
+# Container for project's attributes.
+# Receives a hash with either :project key pointing to an hpricot object or a
+# project_id and a token with which to fetch and build the project object
+class Project
+  attr_reader :name, :iteration_length, :id, :week_start_day, :point_scale, :api_url, :url, :token, :meta
+  
+  def initialize(options = {})
+    @token   = options[:token] || Token.new
+    if options.include?(:project_id)
+      @id      = options[:project_id]
+      @api_url = "#{CONFIG[:api_location]}/projects/#{@id}"
+      @url     = "#{CONFIG[:site_location]}/projects/#{@id}"
+      @project = Hpricot(open(@api_url, {"X-TrackerToken" => @token.to_s}))
+      @stories = nil
+    elsif options.include?(:project)
+      @project = options[:project]
+    else
+      raise ArgumentError, "Valid options are: :project (receives an Hpricot Object) OR :project_id + :token"
+    end
+    build_project
+  end
+  
+  # Builds an array containing the project's stories
+  def stories ; @stories || get_stories ; end
+  
+  def iterations ; @iterations || get_iterations ; end
+  
+  # Fetches a story with given id
+  def story(id)
+    Story.new(:story_id => id, :project_id => @id, :token => @token.to_s)
+  end
+  
+  # Creates a story for this project. Receives a set of valid attributes.
+  # Returns a Story object
+  # TODO: Validate attributes
+  def create_story(attributes = {})
+    api_url = URI.parse("#{CONFIG[:api_location]}/projects/#{@id}/stories")
+    query_string = attributes.map { |key, value| "story[#{key}]=#{CGI::escape(value)}"}.join('&')
+    response = Net::HTTP.start(api_url.host, api_url.port) do |http|
+      http.post(api_url.path, query_string.concat("&token=#{@token.to_s}"))
+    end
+  
+    story = (Hpricot(response.body)/:story)
+    Story.new(:story => story, :project_id => @id, :token => @token.to_s)
+  end
+  
+  # Deletes a story given a Story object or a story_id
+  def delete_story(story)
+    if story.is_a?(Story)
+      api_url = URI.parse("#{CONFIG[:api_location]}/projects/#{@id}/stories/#{story.id}")
+    elsif story.is_a?(Integer) || story.to_i.is_a?(Integer)
+      api_url = URI.parse("#{CONFIG[:api_location]}/projects/#{@id}/stories/#{story}")
+    else
+      raise ArgumentError, "Should receive a story id or a Story object."
+    end
+    response = Net::HTTP.start(api_url.host, api_url.port) do |http|
+      http.delete(api_url.path, {"X-TrackerToken" => @token.to_s})
+    end
+    story = (Hpricot(response.body)/:story)
+    Story.new(:story => story, :project_id => @id, :token => @token.to_s)
+  end
+  
+  def get_iterations(iteration_type=nil)
+    @iterations = Iteration.find(:project_id => @id, :type => iteration_type) || []
+  end
+  
+  # Gets the stories for a given iteration
+  def get_iteration_stories(iteration_type=nil)
+    @stories = get_iterations(iteration_type).stories
+  end
+  
+  def num_stories
+    stories.size || 0
+  end
+  
+  def num_completed_stories
+    num_completed_stories = 0
+    stories.each do |story|
+      num_completed_stories += 1 if completed_statuses.include?(story.current_state)
+    end
+    num_completed_stories
+  end
+  
+  def current_target_date
+    get_iterations.last.finish_date
+  end
+  
+  def completed_statuses
+    %w{ finished delivered accepted }
+  end
+  
+  # Builds an array containing the project's stories
+  protected
+  
+  # Builds a project given an hpricot object stored at instance variable
+  # @project
+  def build_project
+    @id               ||= @project.at('id').inner_html
+    @api_url          ||= "#{CONFIG[:api_location]}/projects/#{@id}"
+    @url              ||= "http://www.pivotaltracker.com/projects/#{@id}"
+    @name             = @project.at('name').inner_html
+    @iteration_length = @project.at('iteration_length').inner_html
+    @week_start_day   = @project.at('week_start_day').inner_html
+    @point_scale      = @project.at('point_scale').inner_html.split(',')
+    @meta             = ProjectMeta.find_by_project_id(@id)
+    if @meta.nil?
+      init_meta
+    else
+      @meta.sync(self)
+    end
+  end
+  
+  def get_stories
+    api_url = "#{CONFIG[:api_location]}/projects/#{@id}/stories"
+    @stories = (Hpricot(open(api_url, {"X-TrackerToken" => @token.to_s}))/:story).map {|story| Story.new(:story => story, :project_id => @id)}
+  end
+  
+  def init_meta
+    @meta = ProjectMeta.create_from_project(self)
+  end
+
+end

data/lib/track-r/story.rb

@@ -0,0 +1,87 @@
+# TODO: Documentation ☻
+class Story
+  attr_accessor :story_type, :estimate, :current_state,
+    :description, :name, :requested_by, :owned_by, :created_at, :accepted_at,
+    :labels
+
+  attr_reader :id, :url
+  
+  def initialize(options = {})
+    @token      = options[:token].to_s || Token.new
+    if options.include?(:project_id) && options.include?(:story_id)
+      @id         = options[:story_id]
+      @project_id = options[:project_id]
+      @url        = "http://www.pivotaltracker.com/story/show/#{@id}"
+      @api_url    = "http://www.pivotaltracker.com/services/v2/projects/#{@project_id}/stories/#{@id}"
+      @story      = Hpricot(open(@api_url, {"X-TrackerToken" => @token}))
+    elsif options.include?(:story) && options.include?(:project_id)
+      @project_id = options[:project_id]
+      @story      = options[:story]
+    else
+      raise ArgumentError, "Valid options are: :story (receives an Hpricot Object) + :project_id OR :project_id + :story_id + :token"
+    end
+    build_story
+  end
+
+  def build_story
+    @id            ||= @story.at('id').inner_html
+    @url           ||= "http://www.pivotaltracker.com/story/show/#{@id}"
+    @api_url       ||= "http://www.pivotaltracker.com/services/v2/projects/#{@project_id}/stories/#{@id}" 
+    @story_type    = @story.at('story_type').inner_html    unless @story.at('story_type').nil?
+    @estimate      = @story.at('estimate').inner_html      unless @story.at('estimate').nil?
+    @current_state = @story.at('current_state').inner_html unless @story.at('current_state').nil?
+    @description   = @story.at('description').inner_html   unless @story.at('description').nil?
+    @name          = @story.at('name').inner_html          unless @story.at('name').nil?
+    @requested_by  = @story.at('requested_by').inner_html  unless @story.at('requested_by').nil?
+    @owned_by      = @story.at('owned_by').inner_html      unless @story.at('owned_by').nil?
+    @created_at    = @story.at('created_at').inner_html    unless @story.at('created_at').nil?
+    @accepted_at   = @story.at('accepted_at').inner_html   unless @story.at('accepted_at').nil?
+    @labels        = @story.at('labels').inner_html        unless @story.at('labels').nil?
+  end
+
+  def save
+    parameters = build_story_xml
+    api_url = URI.parse("http://www.pivotaltracker.com/services/v2/projects/#{@project_id}/stories/#{@id}")
+    response = Net::HTTP.start(api_url.host, api_url.port) do |http|
+      http.put(api_url.path, parameters, {'X-TrackerToken' => @token, 'Content-Type' => 'application/xml'})
+    end
+
+    @story = (Hpricot(response.body)/:story)
+    build_story
+  end
+
+  # TODO: test this method:
+  def destroy
+    api_url = URI.parse("http://www.pivotaltracker.com/services/v2/projects/#{@project_id}/stories/#{@id}")
+    response = Net::HTTP.start(api_url.host, api_url.port) do |http|
+      http.delete(api_url.path, {"X-TrackerToken" => @token})
+    end
+  end
+
+  protected
+
+  def to_param
+    query_string = attributes.map { |key, value| "story[#{key}]=#{CGI::escape(value)}" unless value.nil?}.compact.join('&')
+  end
+
+  def build_story_xml
+    story_xml = "<story>"
+    attributes.each do |key, value|
+      story_xml << "<#{key}>#{(value.to_s)}</#{key}>" unless value.nil?
+    end
+    story_xml << "</story>"
+  end
+
+  def attributes
+    {
+      "story_type"    => @story_type,
+      "estimate"      => @estimate,
+      "current_state" => @current_state,
+      "description"   => @description,
+      "name"          => @name,
+      "requested_by"  => @requested_by,
+      "owned_by"      => @owned_by,
+      "labels"        => @labels
+    }
+  end
+end # class Tracker::Story

data/lib/track-r/token.rb

@@ -0,0 +1,27 @@
+class Token
+	def initialize(options = {})
+		@token = case
+						 when options.include?(:token)
+							 options[:token]
+						 when options.include?(:username) && options.include?(:password)
+							 # If a token is not provided, it can be generated by passing a hash with :user and :password keys
+							 get_token(options[:username], options[:password])
+						 when CONFIG.key?(:api_token)
+							  CONFIG[:api_token]
+						 else
+							 raise ArgumentError, "Invalid argument, expecting either <:token> or <:username> and <:password>"
+						 end
+	end
+
+	def to_s
+		@token.to_s
+	end
+
+	protected
+
+	# According to http://www.pivotaltracker.com/help/api#retrieve_token this should work:
+	def get_token(username, password)
+		(Hpricot(open("https://www.pivotaltracker.com/services/tokens/active", :http_basic_authentication => [username, password])).at('guid')).inner_html
+	end
+
+end # class Tracker::Token

data/lib/track-r/tracker.rb

@@ -0,0 +1,56 @@
+# The class is a wrapper for getting projects, stories and using tokens.  It's
+# main purpose is relating the three allowing to interact with a project, and
+# its stories using a token.
+# Expects a token when initialized.
+class Tracker
+
+  # To generate a token, use the "Create New Token" link on the My Profile
+  # page (http://www.pivotaltracker.com/profile).
+  def initialize(token=nil)
+    @token = token || Token.new
+    raise TypeError unless @token.is_a? Token
+  end
+
+  # Fetches project with given ID
+  # Returns a Project object
+  def project(project_id)
+    @project = Project.new(:project_id => project_id)
+  end
+
+  # Refresh the projects from the server
+  # Returns an array of projects
+  def sync
+    @projects = nil
+    get_projects
+  end
+
+  # Alias for get_projects
+  # Returns an array of projects
+  def projects ; get_projects ; end
+
+  # Receives a block with the condition to find a project. Should work the
+  # same as Enumerable.find method
+  # Returns a Project object
+  def find_project
+    get_projects unless defined?(@projects) && @projects.is_a?(Array)
+    @projects.find do |project|
+      yield(project)
+    end
+  end
+
+  # Uses the ProjectMeta model to find locally stored projects and their api counterparts
+  def self.find_local(is_active=nil)
+    local = ProjectMeta.find_local(is_active)
+    local.map{|meta| Tracker.new.find_project{|project| puts "+++#{meta.project_id} == #{project.id}"; meta.project_id == project.id } } unless local.nil? || local.empty?
+  end
+  
+  protected
+
+  # Fills @projects. NOTE: call sync method to refill/sync @projects
+  # Returns an Array stored in @projects
+  def get_projects
+    api_url = "#{CONFIG[:api_location]}/projects/"
+    @projects ||= (Hpricot(open(api_url, {"X-TrackerToken" => @token.to_s}))/:project).map {|project| Project.new(:project => project)}
+  end
+
+end # class Tracker::Tracker

data/test/test_config.yml.example

@@ -0,0 +1,28 @@
+--- 
+:password: "password"
+:username: an@email.com
+:token:    "a_token_hash"
+:project_count: 2
+:project_1: 
+  :name: AProjectName
+  :id: "12345"
+  :point_scale:
+  - "0"
+  - "1"
+  - "2"
+  - "3"
+  :week_start_day: Monday
+  :iteration_length: "1"
+:project_2: 
+  :name: AnotherProjectName
+  :id: "6890"
+  :point_scale:
+  - "0"
+  - "1"
+  - "2"
+  - "3"
+  :week_start_day: Sunday
+  :iteration_length: "1"
+:story_1:
+  :id: 12345
+  :name: "Some existing name"

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'shoulda'
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '/../lib/track-r.rb')
+require File.join(File.dirname(__FILE__), '/../config/environment.rb')
+$config = YAML.load_file(File.join(File.dirname(__FILE__), '/test_config.yml'))

data/test/unit/project_test.rb

@@ -0,0 +1,44 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class ProjectTest < Test::Unit::TestCase
+  context "A given project" do
+
+    setup do
+      @project_id = $config[:project_1][:id]
+      token_options = {:username => $config[:username], :password => $config[:password]}
+      @tracker = Tracker.new(Token.new(token_options))
+      @project = @tracker.project(@project_id)
+    end
+
+    should "show all stories for that project with @project.stories" do
+      assert_equal $config[:project_1][:story_count], @project.stories.size
+    end
+
+    should "show a story with @project.story and passing the story id as argument" do 
+      assert_equal $config[:story_1][:name], @project.story($config[:story_1][:id]).name
+    end
+
+    should "be able to add and remove a story" do 
+      story_count = @project.stories.size
+      attributes = { :name => "Finish Track-R (sorry for cluttering :))",
+                    :requested_by => "Jose Felix Gomez", 
+                    :description => "This story was made with Track-R library. Sorry for the clutter, you're free to delete me." }
+      new_story = @project.create_story(attributes)
+      assert_equal  "Finish Track-R (sorry for cluttering :))", new_story.name
+      @project.delete_story(new_story)
+      assert_equal story_count, @project.stories.size
+    end
+
+    should "be able to get the backlog stories" do 
+      story_count = $config[:project_1][:backlog_stories]
+      assert_equal story_count, @project.backlog.size
+    end
+
+    should "be able to get the current iteration stories" do 
+      story_count = $config[:project_1][:current_stories]
+      assert_equal story_count, @project.current.size
+    end
+
+  end
+end
+

data/test/unit/story_test.rb

@@ -0,0 +1,32 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class TestStoryTest < Test::Unit::TestCase
+
+  context "A given story" do 
+
+    setup do 
+      token_options = {:username => $config[:username], :password => $config[:password]}
+      @tracker = Tracker.new(Token.new(token_options))
+      @project_id = $config[:project_1][:id]
+      @project = @tracker.project(@project_id)
+      attributes = { :name => "Finish Track-R (sorry for cluttering :))",
+                    :requested_by => "Jose Felix Gomez", 
+                    :description => "This story was made with Track-R library. Sorry for the clutter, you're free to delete me." }
+      @story = @project.create_story(attributes)
+    end
+
+    teardown do
+      @project.delete_story(@story)
+    end
+
+    should "be updated after story.save call" do 
+      @story.name = "More power to the shields"
+      @story.description = "ZOMG!"
+      @story.save
+
+      assert_equal "More power to the shields", @project.story(@story.id).name
+    end
+
+  end
+end
+

data/test/unit/token_test.rb

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class TestTokenTest < Test::Unit::TestCase
+  context "with a valid username and password" do
+
+    setup do
+      def token_options
+        {:username => $config[:username], :password => $config[:password]}
+      end
+    end
+
+    should "return a valid token" do
+      @token = Token.new(token_options)
+      assert_equal $config[:token], @token.to_s
+    end
+
+  end
+end

data/test/unit/tracker_test.rb

@@ -0,0 +1,46 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class TestTrackerTest < Test::Unit::TestCase
+
+  context "with an invalid token" do 
+
+    should "raise an TypeError if token is other than Token object" do 
+      token = "token"
+      assert_raise(TypeError) { Tracker.new(token) }
+    end
+
+  end
+
+  context "with a valid token" do
+
+    setup do
+      @project_id = $config[:project_1][:id]
+      def get_token
+        token_options = {:username => $config[:username], :password => $config[:password]}
+        Token.new(token_options)
+      end
+      @tracker = Tracker.new(get_token)
+    end
+
+    should "return a valid project by passing the id with correct attributes" do 
+      project = @tracker.project(@project_id)
+      assert_equal $config[:project_1][:name], project.name
+      assert_equal $config[:project_1][:point_scale], project.point_scale
+      assert_equal $config[:project_1][:week_start_day], project.week_start_day
+      assert_equal $config[:project_1][:iteration_length], project.iteration_length
+    end
+
+    should "return an array of all my projects" do 
+      projects = @tracker.projects
+      assert_equal $config[:project_count], projects.size
+    end
+
+    should "be able to find a project using Enumerable.find method" do 
+      project_1 = (@tracker.find_project {|project| project.name == $config[:project_1][:name]})
+      project_2 = (@tracker.find_project {|project| project.id == $config[:project_2][:id]})
+      assert_equal $config[:project_1][:name], project_1.name, "Failed to find by name"
+      assert_equal $config[:project_2][:name], project_2.name, "Failed to find by id"
+    end
+  end
+
+end

data/vendor/install-gems/install-gems.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+#-------------------------------------------------------------------------------.
+# InstallGems: Script to do the hard gem installing and letting you rest a bit. ||
+#                                                                               ||
+# AUTHOR: Jose F. Gomez                                                         ||
+# VERSION: 0.2.0                                                                ||
+# DATE: 2009-04-04                                                              ||
+#                                                                               ||
+# USAGE: install-gems.rb [file.yml] The yml file should have this format per    ||
+# gem:                                                                          ||
+#                                                                               ||
+# example.yml:                                                                  ||
+# ---                                                                           ||
+# - :source: http://gems.github.com                                             ||
+#   :version: = 0.1.99.21                                                       ||
+#   :name: aslakhellesoy-cucumber                                               ||
+#                                                                               ||
+# Note that :source and :version are optional and the script checks wheter a    ||
+# gem is already installed or not.                                              ||
+#                                                                               ||
+#-------------------------------------------------------------------------------´
+#  HISTORY
+#  0.2.0  -- Made script require-able.
+#  0.1.0  -- Initial Commit
+
+
+class InstallGems
+  require 'yaml'
+  require 'rubygems'
+
+  def initialize(file)
+    @gems_yml = YAML.load_file(file)
+    install_gems
+  end
+
+  def install_gems
+    for gem in @gems_yml
+      install_gem(gem)
+    end
+  end
+
+  def install_gem(gem)
+    unless Gem.available? gem[:name]
+      cmd = "gem install "
+      cmd += "--version '%s' " % gem[:version] if gem.has_key? :version
+      cmd += "--source %s " % gem[:source] if gem.has_key? :source
+      cmd += "%s " % gem[:name] if gem.has_key? :name
+      puts "Installing: %+28s"  % gem[:name]
+      out = %x[#{cmd}]
+    else
+      puts "*** [ #{gem[:name]} ] is already installed on this system."
+    end
+  end
+end
+
+if __FILE__ == $0
+  app = InstallGems.new(ARGV[0])
+end
+
+#-------------------------------------------------------------------------------.
+# vim: set foldmethod:indent                                                    ||
+#-------------------------------------------------------------------------------´
+

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: localshred-track-r
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jose Felix Gomez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-15 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: track-r is a library that provides wrapper classes and methods for accessing PivotalTracker's public API.
+email: jfgomez86@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- .gitignore
+- README.textile
+- Rakefile
+- VERSION
+- config/config.yml
+- config/environment.rb
+- config/gems.yml
+- lib/track-r.rb
+- lib/track-r/api_connector/connection.rb
+- lib/track-r/api_connector/request.rb
+- lib/track-r/api_connector/response.rb
+- lib/track-r/iteration.rb
+- lib/track-r/project.bak.rb
+- lib/track-r/project.rb
+- lib/track-r/story.rb
+- lib/track-r/token.rb
+- lib/track-r/tracker.rb
+- pkg/track-r-1.0.0.gem
+- test/test_config.yml.example
+- test/test_helper.rb
+- test/unit/project_test.rb
+- test/unit/story_test.rb
+- test/unit/token_test.rb
+- test/unit/tracker_test.rb
+- vendor/install-gems/install-gems.rb
+has_rdoc: false
+homepage: http://github.com/jfgomez86/Track-R
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A wrapper library for pivotal tracker's API
+test_files: 
+- test/test_helper.rb
+- test/unit/project_test.rb
+- test/unit/story_test.rb
+- test/unit/token_test.rb
+- test/unit/tracker_test.rb