tracker_api 1.7.1 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cbd6533872fb55f68afdf21309b4187d7061b8a6
-  data.tar.gz: 71b0f57265c1840a1271f3025406aef56896e5c5
+  metadata.gz: cce8ed0f32ae28c44915d1a2aa0dff3f7deb44f9
+  data.tar.gz: 6478d86c0e8e8e826e0ffd50b8111758f0dec9c0
 SHA512:
-  metadata.gz: 88cff726815d37af8312853895bed38974eefb993d1bbc00050fcf63bf393f2d8a6618d1a72df6ae0cbf0a0124deff6ee48f9798bc13027da0bac8a73c31ca7f
-  data.tar.gz: a1a864149b4175c72f345ff143b60f16dd2a992d848fd55fd39300287f71e5a0000a0eacdd30783d095d70927ecc2ffbf9207b48616fc62a98ea0a57f5657c06
+  metadata.gz: 34b10827d2868cf6e0de4039ef23444b412fcb5d162e6fca2a20258f22d3ceede1e45cb4f7e829cb57ccd8a66a3506144e53eed8f7ae6954b2d2196c6244e0f1
+  data.tar.gz: 69eb1bbad1ea7a6ef35b84e36c9b856ebc300eda60369769c242a9ec77fd5cf3c436c7280101341f657d46beab1fc382e16bbb43c074bcb6b89c97b74d71105b

data/.travis.yml

@@ -5,7 +5,8 @@ rvm:
   - 2.2
   - 2.3
   - 2.4
-  # - "jruby"
+  - 2.5
+  - "jruby"
   #  - rbx
   #  - "1.8.7"
 # uncomment this line if your project needs to run something other than `rake`:

data/README.md

@@ -68,9 +68,20 @@ comments = story.comments                                                 #   co
 
 comment = story.create_comment(text: "Use the force!")                    # Create a new comment on the story
 
+comment = story.create_comment(text: "Use the force again !",             # Create a new comment on the story with
+                                files: ['path/to/an/existing/file'])      #     file attachments
+
 comment.text += " (please be careful)"
 comment.save                                                              # Update text of an existing comment
+comment.delete                                                            # Delete an existing comment
+
+comment.create_attachments(files: ['path/to/an/existing/file'])           # Add attachments to existing comment
+comment.delete_attachments                                                # Delete all attachments from a comment
 
+attachments = comment.attachments                                         # Get attachments associated with a comment
+attachments.first.delete                                                  # Delete a specific attachment
+
+comment.attachments(reload: true)                                         # Re-load the attachments after modification
 task = story.tasks.first                                                  # Get story tasks
 task.complete = true
 task.save                                                                 # Mark a task complete
@@ -95,6 +106,10 @@ client.project(project_id).stories(fields: ':default,tasks')              # Eage
 story.comments(fields: ':default,person')                                 # Eagerly get comments and the person that made the comment for a story
 ```
 
+## Error Handling
+`TrackerApi::Errors::ClientError` is raised for 4xx HTTP status codes  
+`TrackerApi::Errors::ServerError` is raised for 5xx HTTP status codes
+
 ## Warning
 
 Direct mutation of an attribute value skips coercion and dirty tracking. Please use direct assignment or the specialized add_* methods to get expected behavior.
@@ -118,6 +133,7 @@ story.save
 
 - Add missing resources and endpoints
 - Add create, update, delete for resources
+- Error handling for [error responses](https://www.pivotaltracker.com/help/api#Error_Responses)
 
 ## Semantic Versioning
 http://semver.org/

data/lib/tracker_api.rb

@@ -3,6 +3,8 @@ require 'tracker_api/version'
 # dependencies
 require 'faraday'
 require 'faraday_middleware'
+require 'pathname'
+require 'mimemagic'
 
 if defined?(ActiveSupport)
   require 'active_support/core_ext/object/blank'
@@ -26,15 +28,20 @@ module TrackerApi
   autoload :Error, 'tracker_api/error'
   autoload :Client, 'tracker_api/client'
   autoload :Logger, 'tracker_api/logger'
+  autoload :FileUtility, 'tracker_api/file_utility'
 
   module Errors
     class UnexpectedData < StandardError; end
+    class ClientError < Error; end
+    class ServerError < Error; end
   end
 
   module Endpoints
     autoload :Activity, 'tracker_api/endpoints/activity'
+    autoload :Blockers, 'tracker_api/endpoints/blockers'
     autoload :Epic, 'tracker_api/endpoints/epic'
     autoload :Epics, 'tracker_api/endpoints/epics'
+    autoload :Iteration, 'tracker_api/endpoints/iteration'
     autoload :Iterations, 'tracker_api/endpoints/iterations'
     autoload :Labels, 'tracker_api/endpoints/labels'
     autoload :Me, 'tracker_api/endpoints/me'
@@ -55,6 +62,11 @@ module TrackerApi
     autoload :Webhook, 'tracker_api/endpoints/webhook'
     autoload :Webhooks, 'tracker_api/endpoints/webhooks'
     autoload :StoryTransitions, 'tracker_api/endpoints/story_transitions'
+    autoload :Attachment, 'tracker_api/endpoints/attachment'
+    autoload :Attachments, 'tracker_api/endpoints/attachments'
+    autoload :Releases, 'tracker_api/endpoints/releases'
+    autoload :Release, 'tracker_api/endpoints/release'
+    autoload :Reviews, 'tracker_api/endpoints/reviews'
   end
 
   module Resources
@@ -64,6 +76,7 @@ module TrackerApi
     end
     autoload :Activity, 'tracker_api/resources/activity'
     autoload :Account, 'tracker_api/resources/account'
+    autoload :Blocker, 'tracker_api/resources/blocker'
     autoload :Change, 'tracker_api/resources/change'
     autoload :Epic, 'tracker_api/resources/epic'
     autoload :EpicsSearchResult, 'tracker_api/resources/epics_search_result'
@@ -85,5 +98,11 @@ module TrackerApi
     autoload :Comment, 'tracker_api/resources/comment'
     autoload :Webhook, 'tracker_api/resources/webhook'
     autoload :StoryTransition, 'tracker_api/resources/story_transition'
+    autoload :FileAttachment, 'tracker_api/resources/file_attachment'
+    autoload :Release, 'tracker_api/resources/release'
+    autoload :CycleTimeDetails, 'tracker_api/resources/cycle_time_details'
+    autoload :DailyHistoryContainer, 'tracker_api/resources/daily_history_container'
+    autoload :Review, 'tracker_api/resources/review'
+    autoload :ReviewType, 'tracker_api/resources/review_type'
   end
 end

data/lib/tracker_api/client.rb

@@ -25,7 +25,7 @@ module TrackerApi
       @url               = Addressable::URI.parse(url).to_s
       @api_version       = options.fetch(:api_version, '/services/v5')
       @logger            = options.fetch(:logger, ::Logger.new(nil))
-      adapter            = options.fetch(:adapter, :excon)
+      adapter            = options.fetch(:adapter) { defined?(JRUBY_VERSION) ? :net_http : :excon }
       connection_options = options.fetch(:connection_options, { ssl: { verify: true } })
       @auto_paginate     = options.fetch(:auto_paginate, true)
       @token             = options[:token]
@@ -36,7 +36,7 @@ module TrackerApi
       @connection = Faraday.new({ url: @url }.merge(connection_options)) do |builder|
         # response
         builder.use Faraday::Response::RaiseError
-        builder.response :json
+        builder.response :json, content_type: /\bjson/ # e.g., 'application/json; charset=utf-8'
 
         # request
         builder.request :multipart
@@ -48,40 +48,15 @@ module TrackerApi
       end
     end
 
-    # Make a HTTP GET request
+    # HTTP requests methods
     #
     # @param path [String] The path, relative to api endpoint
     # @param options [Hash] Query and header params for request
     # @return [Faraday::Response]
-    def get(path, options = {})
-      request(:get, parse_query_and_convenience_headers(path, options))
-    end
-
-    # Make a HTTP POST request
-    #
-    # @param path [String] The path, relative to api endpoint
-    # @param options [Hash] Query and header params for request
-    # @return [Faraday::Response]
-    def post(path, options = {})
-      request(:post, parse_query_and_convenience_headers(path, options))
-    end
-
-    # Make a HTTP PUT request
-    #
-    # @param path [String] The path, relative to api endpoint
-    # @param options [Hash] Query and header params for request
-    # @return [Faraday::Response]
-    def put(path, options = {})
-      request(:put, parse_query_and_convenience_headers(path, options))
-    end
-
-    # Make a HTTP DELETE request
-    #
-    # @param path [String] The path, relative to api endpoint
-    # @param options [Hash] Query and header params for request
-    # @return [Faraday::Response]
-    def delete(path, options = {})
-      request(:delete, parse_query_and_convenience_headers(path, options))
+    %i{get post patch put delete}.each do |verb|
+      define_method verb do |path, options = {}|
+        request(verb, parse_query_and_convenience_headers(path, options))
+      end
     end
 
     # Make one or more HTTP GET requests, optionally fetching
@@ -215,7 +190,8 @@ module TrackerApi
       opts[:params] = options[:params] || {}
       opts[:token]  = options[:token] || @token
       headers       = { 'User-Agent'     => USER_AGENT,
-                        'X-TrackerToken' => opts.fetch(:token) }.merge(options.fetch(:headers, {}))
+                        'X-TrackerToken' => opts.fetch(:token),
+                        'Accept' => 'application/json' }.merge(options.fetch(:headers, {}))
 
       CONVENIENCE_HEADERS.each do |h|
         if header = options[h]
@@ -247,8 +223,13 @@ module TrackerApi
         req.body = body
       end
       response
-    rescue Faraday::Error::ClientError => e
-      raise TrackerApi::Error.new(e)
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      status_code = e.response[:status]
+      case status_code
+      when 400..499 then raise TrackerApi::Errors::ClientError.new(e)
+      when 500..599 then raise TrackerApi::Errors::ServerError.new(e)
+      else raise "Expected 4xx or 5xx HTTP status code; got #{status_code} instead."
+      end
     end
 
     class Pagination

data/lib/tracker_api/endpoints/attachment.rb

@@ -0,0 +1,38 @@
+module TrackerApi
+  module Endpoints
+    class Attachment
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def create(comment, file)
+        data = client.post("/projects/#{comment.project_id}/uploads", body: FileUtility.get_file_upload(file)).body
+        Resources::FileAttachment.new({ comment: comment }.merge(data))
+      end
+
+      # TODO : Discuss before implementing this as it orphans the file.
+      # It deletes source, but the file name appears in the comments
+      # def delete(comment, file_attachment_id)
+      #   client.delete("/projects/#{comment.project_id}/stories/#{comment.story_id}/comments/#{comment.id}/file_attachments/#{file_attachment_id}").body
+      # end
+
+      def get(comment)
+        data = client.get("/projects/#{comment.project_id}/stories/#{comment.story_id}/comments/#{comment.id}?fields=file_attachments").body["file_attachments"]
+        raise Errors::UnexpectedData, 'Array of file attachments expected' unless data.is_a? Array
+
+        data.map do |file_attachment|
+          Resources::FileAttachment.new({ comment: comment }.merge(file_attachment))
+        end
+      end
+
+      # TODO : Implement this properly.
+      # This results in either content of the file or an S3 link.
+      # the S3 link is also present in big_url attribute.
+      # def download(download_path)
+      #   client.get(download_path, url: '').body
+      # end
+    end
+  end
+end

data/lib/tracker_api/endpoints/attachments.rb

@@ -0,0 +1,22 @@
+module TrackerApi
+  module Endpoints
+    class Attachments
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+
+      def create(comment, files)
+        return [] if files.to_a.empty?
+        #Check files before upload to make it all or none.
+        FileUtility.check_files_exist(files)
+        attachment = Endpoints::Attachment.new(client)
+        files.map do | file |
+          attachment.create(comment, file)
+        end  
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/blockers.rb

@@ -0,0 +1,20 @@
+module TrackerApi
+  module Endpoints
+    class Blockers
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, story_id, params = {})
+        data = client.get("/projects/#{project_id}/stories/#{story_id}/blockers", params: params).body
+        raise Errors::UnexpectedData, 'Array of Blockers expected' unless data.is_a? Array
+
+        data.map do |blocker|
+          Resources::Blocker.new({ client: client, project_id: project_id }.merge(blocker))
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/comment.rb

@@ -15,13 +15,20 @@ module TrackerApi
       def update(comment, params={})
         raise ArgumentError, 'Valid comment required to update.' unless comment.instance_of?(Resources::Comment)
 
-        data = client.put("/projects/#{comment.project_id}/stories/#{comment.story_id}/comments/#{comment.id}",
-                          params: params).body
+        path = "/projects/#{comment.project_id}/stories/#{comment.story_id}/comments/#{comment.id}"
+        path += "?fields=:default,file_attachments" if params.represented.file_attachment_ids_to_add.present? || params.represented.file_attachment_ids_to_remove.present?
+        data = client.put(path, params: params).body
 
         comment.attributes = data
         comment.clean!
         comment
       end
+
+      def delete(comment)
+        raise ArgumentError, 'Valid comment required to update.' unless comment.instance_of?(Resources::Comment)
+
+        client.delete("/projects/#{comment.project_id}/stories/#{comment.story_id}/comments/#{comment.id}").body
+      end
     end
   end
 end

data/lib/tracker_api/endpoints/iteration.rb

@@ -0,0 +1,35 @@
+module TrackerApi
+  module Endpoints
+    class Iteration
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, iteration_number)
+        data = client.get("/projects/#{project_id}/iterations/#{iteration_number}").body
+
+        Resources::Iteration.new({ client: client, project_id: project_id }.merge(data))
+      end
+
+      def get_analytics_cycle_time_details(project_id, iteration_number)
+        data = client.paginate("/projects/#{project_id}/iterations/#{iteration_number}/analytics/cycle_time_details")
+        raise Errors::UnexpectedData, 'Array of cycle time details expected' unless data.is_a? Array
+
+        data.map do |cycle_time_details|
+          Resources::CycleTimeDetails.new(
+            { project_id: project_id, iteration_number: iteration_number }.merge(cycle_time_details)
+          )
+        end
+      end
+
+      def get_history(project_id, iteration_number)
+        data = client.get("/projects/#{project_id}/history/iterations/#{iteration_number}/days").body
+        raise Errors::UnexpectedData, 'Hash of history data expected' unless data.is_a? Hash
+
+        Resources::DailyHistoryContainer.new({ project_id: project_id, iteration_number: iteration_number }.merge(data))
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/release.rb

@@ -0,0 +1,17 @@
+module TrackerApi
+  module Endpoints
+    class Release
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, id, params={})
+        data = client.get("/projects/#{project_id}/releases/#{id}", params: params).body
+
+        Resources::Release.new({ client: client }.merge(data))
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/releases.rb

@@ -0,0 +1,20 @@
+module TrackerApi
+  module Endpoints
+    class Releases
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, params={})
+        data = client.paginate("/projects/#{project_id}/releases", params: params)
+        raise Errors::UnexpectedData, 'Array of releases expected' unless data.is_a? Array
+
+        data.map do |release|
+          Resources::Release.new({ client: client, project_id: project_id }.merge(release))
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/reviews.rb

@@ -0,0 +1,21 @@
+module TrackerApi
+  module Endpoints
+    class Reviews
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(project_id, story_id, params={})
+        params[:fields] ||= ":default,review_type"
+        data = client.paginate("/projects/#{project_id}/stories/#{story_id}/reviews", params: params)
+        raise Errors::UnexpectedData, 'Successful responses to this request return an array containing zero or more instances of the review resource. This response was not an array.' unless data.is_a? Array
+
+        data.map do |review|
+          Resources::Review.new({ client: client, project_id: project_id }.merge(review))
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/search.rb

@@ -10,7 +10,7 @@ module TrackerApi
       def get(project_id, query, options={})
         raise ArgumentError, 'Valid query string required to search' unless query.is_a?(String)
 
-        options.key?(:body) ? options[:body][:query] = query : options[:body] = { query: query }
+        options[:params] = { query: query }
         data = client.get("/projects/#{project_id}/search", options).body
 
         raise Errors::UnexpectedData, 'Hash of search results expect' unless data.is_a? Hash

data/lib/tracker_api/endpoints/stories.rb

@@ -17,6 +17,16 @@ module TrackerApi
           Resources::Story.new({ client: client, project_id: project_id }.merge(story))
         end
       end
+
+      def get_release(project_id, release_id, params={})
+        data = client.paginate("/projects/#{project_id}/releases/#{release_id}/stories", params: params)
+
+        raise Errors::UnexpectedData, 'Array of stories expected' unless data.is_a? Array
+
+        data.map do |story|
+          Resources::Story.new({ client: client, project_id: project_id }.merge(story))
+        end
+      end
     end
   end
 end