tracker_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8407c876c55351601c4fd2648ced15f1af1336b3
+  data.tar.gz: 983fcb13633fd259089a96eab64accc1ea49a777
+SHA512:
+  metadata.gz: d5cb62b0d1e08ea319e1b88281216a5874e13c8d431f391b43002d46571db29d210cd8294ed2cea1ff58608814145a4092ded83d527d84584a6fc0736b301f6c
+  data.tar.gz: 777c67421852258ef4a05e0165f4aa6de55c9ea207b03966fb383ba6f520c34cec821107f0dd2e9f14a3f5553fed7149cd57959940ea2a970c06f2fd9cefda9d

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.idea
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+  - "2.1.0"
+  # Faraday::ConnectionFailed: Could not generate DH keypair (Java::JavaLang::RuntimeException)
+  # http://bugs.java.com/bugdatabase/view_bug.do?bug_id=7044060
+  #  - jruby-19mode # JRuby in 1.9 mode
+  - rbx
+  #  - "1.8.7"
+# uncomment this line if your project needs to run something other than `rake`:
+# script: bundle exec rspec spec

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+0.1.0
+---
+- Initial release.

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tracker_api.gemspec
+gemspec
+
+gem 'coveralls', group: :test, require: false
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Dash of Code
+
+MIT License
+
+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.md

@@ -0,0 +1,57 @@
+# TrackerApi
+
+[![Gem Version](https://badge.fury.io/rb/tracker_api.png)](http://badge.fury.io/rb/tracker_api)
+[![Build Status](https://travis-ci.org/dashofcode/tracker_api.png?branch=master)](https://travis-ci.org/dashofcode/tracker_api)
+[![Code Climate](https://codeclimate.com/github/dashofcode/tracker_api.png)](https://codeclimate.com/github/dashofcode/tracker_api)
+[![Coverage Status](https://coveralls.io/repos/dashofcode/tracker_api/badge.png?branch=master)](https://coveralls.io/r/dashofcode/tracker_api?branch=master)
+[![Dependency Status](https://gemnasium.com/dashofcode/tracker_api.png)](https://gemnasium.com/dashofcode/tracker_api)
+
+This gem allows you to easily use the [Pivotal Tracker v5 API](https://www.pivotaltracker.com/help/api/rest/v5).
+
+It’s powered by [Faraday](https://github.com/lostisland/faraday) and [Virtus](https://github.com/solnic/virtus).
+
+
+## Basic Usage
+
+```ruby
+client = TrackerApi::Client.new(token: 'my-api-token')                    # Create API client
+
+projects = client.projects                                                # Get all projects
+project  = client.project(123456)                                         # Find project with given ID
+
+project.stories                                                           # Get all stories for a project
+project.stories(with_state: :unscheduled, limit: 10)                      # Get 10 unscheduled stories for a project
+project.stories(filter: 'requester:OWK label:"jedi stuff"')               # Get all stories that match the given filters
+project.story(847762630)                                                  # Find a story with the given ID
+
+epics = project.epics                                                     # Get all epics for a project
+epic  = epics.first
+label = epic.label                                                        # Get an epic's label
+```
+
+## Eager Loading
+
+See Pivotal Tracker API [documentation](https://www.pivotaltracker.com/help/api#Response_Controlling_Parameters) for how to use the `fields` parameter.
+
+```ruby
+client = TrackerApi::Client.new(token: 'my-api-token')                    # Create API client
+
+client.project(project_id, fields: ':default,labels(name)')               # Eagerly get labels with a project
+client.project(project_id, fields: ':default,epics')                      # Eagerly get epics with a project
+```
+
+## TODO
+
+- Pagination
+- Create, Update, Delete of Resources
+
+## Contributing
+
+Currently this client supports read-only access to Pivotal Tracker.
+We will be extending it as our use cases require, but are always happy to accept contributions.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,18 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/tracker_api.rb

@@ -0,0 +1,39 @@
+require 'tracker_api/version'
+
+# dependencies
+require 'virtus'
+require 'faraday'
+require 'faraday_middleware'
+
+# stdlib
+require 'forwardable'
+require 'logger'
+
+module TrackerApi
+  autoload :Error, 'tracker_api/error'
+  autoload :Client, 'tracker_api/client'
+  autoload :Logger, 'tracker_api/logger'
+
+  module Errors
+    class UnexpectedData < StandardError; end
+  end
+
+  module Endpoints
+    autoload :Epic, 'tracker_api/endpoints/epic'
+    autoload :Epics, 'tracker_api/endpoints/epics'
+    autoload :Iterations, 'tracker_api/endpoints/iterations'
+    autoload :Project, 'tracker_api/endpoints/project'
+    autoload :Projects, 'tracker_api/endpoints/projects'
+    autoload :Stories, 'tracker_api/endpoints/stories'
+  end
+
+  module Resources
+    autoload :Account, 'tracker_api/resources/account'
+    autoload :Epic, 'tracker_api/resources/epic'
+    autoload :Iteration, 'tracker_api/resources/iteration'
+    autoload :Label, 'tracker_api/resources/label'
+    autoload :Project, 'tracker_api/resources/project'
+    autoload :Story, 'tracker_api/resources/story'
+    autoload :TimeZone, 'tracker_api/resources/time_zone'
+  end
+end

data/lib/tracker_api/client.rb

@@ -0,0 +1,71 @@
+module TrackerApi
+  class Client
+    USER_AGENT = "Ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM}; #{RUBY_ENGINE}) TrackerApi/#{TrackerApi::VERSION} Faraday/#{Faraday::VERSION}".freeze
+
+    attr_accessor :url, :api_version, :token, :logger, :connection
+
+    # Create Pivotal Tracker API client.
+    #
+    # @param [Hash] options the connection options
+    # @option options [String] :token API token to use for requests
+    # @option options [String] :url Main HTTP API root
+    # @option options [String] :api_version The API version URL path
+    # @option options [String] :logger Custom logger
+    # @option options [String] :adapter Custom http adapter to configure Faraday with
+    # @option options [String] :connection_options Connection options to pass to Faraday
+    #
+    # @example Creating a Client
+    #   Client.new token: 'my-super-special-token'
+    def initialize(options={})
+      url  = options[:url] || 'https://www.pivotaltracker.com'
+      @url = URI.parse(url).to_s
+
+      @api_version       = options[:api_version] || '/services/v5'
+      @logger            = options[:logger] || Logger.new(nil)
+      adapter            = options[:adapter] || :net_http
+      connection_options = options[:connection_options] || { ssl: { verify: true } }
+      @token             = options[:token]
+
+      raise 'Missing required options: :token' unless @token
+
+      @connection = Faraday.new({ url: @url }.merge(connection_options)) do |builder|
+        # response
+        builder.use Faraday::Response::RaiseError
+        builder.response :json
+
+        # request
+        builder.request :multipart
+        builder.request :json
+
+        builder.use TrackerApi::Logger, @logger
+        builder.adapter adapter
+      end
+    end
+
+    def request(options={})
+      method  = options[:method] || :get
+      url     = options[:url] || File.join(@url, @api_version, options[:path])
+      token   = options[:token] || @token
+      params  = options[:params] || {}
+      body    = options[:body]
+      headers = { 'User-Agent' => USER_AGENT, 'X-TrackerToken' => token }.merge(options[:headers] || {})
+
+      connection.send(method) do |req|
+        req.url url
+        req.headers.merge!(headers)
+        req.params.merge!(params)
+        req.body = body
+      end
+    rescue Faraday::Error::ClientError => e
+      raise TrackerApi::Error.new(e)
+    end
+
+    def projects(params={})
+      Endpoints::Projects.new(self).get(params)
+    end
+
+    def project(id, params={})
+      Endpoints::Project.new(self).get(id, params)
+    end
+  end
+end

data/lib/tracker_api/endpoints/epic.rb

@@ -0,0 +1,20 @@
+module TrackerApi
+  module Endpoints
+    class Epic
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, id)
+        data = client.request(
+            method: :get,
+            :path => "/projects/#{project_id}/epics/#{id}"
+        ).body
+
+        Resources::Epic.new({ client: client }.merge(data))
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/epics.rb

@@ -0,0 +1,22 @@
+module TrackerApi
+  module Endpoints
+    class Epics
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, params={})
+        data = client.request(
+            method: :get,
+            path:   "/projects/#{project_id}/epics",
+            params: params
+        ).body
+        raise TrackerApi::Errors::UnexpectedData, 'Array of epics expected' unless data.is_a? Array
+
+        data.map { |epic| Resources::Epic.new({ client: client }.merge(epic)) }
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/iterations.rb

@@ -0,0 +1,22 @@
+module TrackerApi
+  module Endpoints
+    class Iterations
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, params={})
+        data = client.request(
+            method: :get,
+            path:   "/projects/#{project_id}/iterations",
+            params: params
+        ).body
+        raise TrackerApi::Errors::UnexpectedData, 'Array of iterations expected' unless data.is_a? Array
+
+        data.map { |iteration| Resources::Iteration.new({ client: client }.merge(iteration)) }
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/project.rb

@@ -0,0 +1,21 @@
+module TrackerApi
+  module Endpoints
+    class Project
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(id, params={})
+        data = client.request(
+            method: :get,
+            path:   "/projects/#{id}",
+            params: params
+        ).body
+
+        Resources::Project.new({ client: client }.merge(data))
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/projects.rb

@@ -0,0 +1,22 @@
+module TrackerApi
+  module Endpoints
+    class Projects
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(params={})
+        data = client.request(
+            method: :get,
+            path:   '/projects',
+            params: params
+        ).body
+        raise TrackerApi::Errors::UnexpectedData, 'Array of projects expected' unless data.is_a? Array
+
+        data.map { |project| Resources::Project.new({ client: client }.merge(project)) }
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/stories.rb

@@ -0,0 +1,22 @@
+module TrackerApi
+  module Endpoints
+    class Stories
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, params={})
+        data = client.request(
+            method: :get,
+            path:   "/projects/#{project_id}/stories",
+            params: params
+        ).body
+        raise TrackerApi::Errors::UnexpectedData, 'Array of stories expected' unless data.is_a? Array
+
+        data.map { |story| Resources::Story.new({ client: client }.merge(story)) }
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/story.rb

@@ -0,0 +1,20 @@
+module TrackerApi
+  module Endpoints
+    class Story
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, id)
+        data = client.request(
+            method: :get,
+            :path => "/projects/#{project_id}/stories/#{id}"
+        ).body
+
+        Resources::Story.new({ client: client }.merge(data))
+      end
+    end
+  end
+end

data/lib/tracker_api/error.rb

@@ -0,0 +1,18 @@
+module TrackerApi
+  class Error < StandardError
+    attr_reader :wrapped_exception, :response
+
+    def initialize(wrapped_exception)
+      @wrapped_exception = wrapped_exception
+      @response          = wrapped_exception.response
+      message            = if wrapped_exception.is_a?(Faraday::Error::ParsingError)
+                             wrapped_exception.message
+                           elsif wrapped_exception.is_a?(Faraday::Error::ClientError)
+                             wrapped_exception.response.inspect
+                           else
+                             wrapped_exception.instance_variable_get(:@wrapped_exception).inspect
+                           end
+      super(message)
+    end
+  end
+end