tracker_api 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b9b4b422159e2a7ed286a626f35cc996a8dcb218
-  data.tar.gz: fa36b559c306a27b509d2314d52b9a795c6d69f3
+  metadata.gz: 4a725b042575ce91d5fe34fae3754d7f14ebad3b
+  data.tar.gz: 3922fb5873893235e94de37dc705954965215604
 SHA512:
-  metadata.gz: 620622ef5cc89906fb1d025d83c2507f9ae92f965501f8acf756fe8780ba30e37fa589c2c777e9cbfcd8c143419915537ec7c64ea195a9a190e3155916747cce
-  data.tar.gz: e8af9bb5b17c3863ebe7e5f1e2e6c5656a238ad6702fbd5c8c96a07a92390ed493ccf862d209be87f89f72a72c500dedaeeee3c752651d346276649377838862
+  metadata.gz: dc75849fe80c0a8a4614149dc1ad7d77b7bf9d6b036d0d305120ad2f8a1201e4fac7815a71b1496ce3894c7e96796e9a87f25132278353635cb0fa4383f2fba4
+  data.tar.gz: e639910732c78410d570e198f965dfa0ae00ec39ce0e7171e2cc89e3d11976627acc46c4c0a16870c9476a7e87eea7eb8367a6b89584d634da5db01a66cebbe5

data/.gitignore

@@ -4,6 +4,7 @@
 .config
 .yardoc
 .idea
+.DS_Store
 Gemfile.lock
 InstalledFiles
 _yardoc

data/README.md

@@ -35,17 +35,26 @@ $ gem install tracker_api
 ```ruby
 client = TrackerApi::Client.new(token: 'my-api-token')                    # Create API client
 
-user_email = client.me.email                                              # Get authenticated user's email
+client.me.email                                                           # Get email for the authenticated person
+client.activity                                                           # Get a list of all the activity performed the authenticated person
+client.notifications                                                      # Get notifications for the authenticated person
 
 projects = client.projects                                                # Get all projects
 project  = client.project(123456)                                         # Find project with given ID
+project.activity                                                          # Get a list of all the activity performed on this project
 
 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
 project.create_story(name: 'Destroy death star')                          # Create a story with the name 'Destroy death star'
 
+story = project.story(847762630)                                          # Find a story with the given ID
+story.activity                                                            # Get a list of all the activity performed on this story
+
+story.name = 'Save the Ewoks'                                             # Update a single story attribute
+story.attributes = { name: 'Save the Ewoks', description: '...' }         # Update multiple story attributes
+story.save                                                                # Save changes made to a story
+
 epics = project.epics                                                     # Get all epics for a project
 epic  = epics.first
 label = epic.label                                                        # Get an epic's label

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, :net_http)
+      adapter            = options.fetch(:adapter, :excon)
       connection_options = options.fetch(:connection_options, { ssl: { verify: true } })
       @auto_paginate     = options.fetch(:auto_paginate, true)
       @token             = options[:token]
@@ -63,6 +63,15 @@ module TrackerApi
       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 one or more HTTP GET requests, optionally fetching
     # the next page of results from information passed back in headers
     # based on value in {#auto_paginate}.
@@ -131,6 +140,22 @@ module TrackerApi
       Endpoints::Story.new(self).get_story(story_id)
     end
 
+    # Get notifications for the authenticated person
+    #
+    # @param [Hash] params
+    # @return [Array[TrackerApi::Resources::Notification]]
+    def notifications(params={})
+      Endpoints::Notifications.new(self).get(params)
+    end
+
+    # Provides a list of all the activity performed the authenticated person.
+    #
+    # @param [Hash] params
+    # @return [Array[TrackerApi::Resources::Activity]]
+    def activity(params={})
+      Endpoints::Activity.new(self).get(params)
+    end
+
     private
 
     def parse_query_and_convenience_headers(path, options)

data/lib/tracker_api/endpoints/activity.rb

@@ -0,0 +1,38 @@
+module TrackerApi
+  module Endpoints
+    class Activity
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(params={})
+        data = client.paginate("/my/activity", params: params)
+        raise TrackerApi::Errors::UnexpectedData, 'Array of activities expected' unless data.is_a? Array
+
+        data.map do |activity|
+          Resources::Activity.new({ client: client }.merge(activity))
+        end
+      end
+
+      def get_project(project_id, params={})
+        data = client.paginate("/projects/#{project_id}/activity", params: params)
+        raise TrackerApi::Errors::UnexpectedData, 'Array of activities expected' unless data.is_a? Array
+
+        data.map do |activity|
+          Resources::Activity.new({ client: client }.merge(activity))
+        end
+      end
+
+      def get_story(project_id, story_id, params={})
+        data = client.paginate("/projects/#{project_id}/stories/#{story_id}/activity", params: params)
+        raise TrackerApi::Errors::UnexpectedData, 'Array of activities expected' unless data.is_a? Array
+
+        data.map do |activity|
+          Resources::Activity.new({ client: client }.merge(activity))
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/epic.rb

@@ -10,7 +10,7 @@ module TrackerApi
       def get(project_id, id)
         data = client.get("/projects/#{project_id}/epics/#{id}").body
 
-        Resources::Epic.new({ client: client, project_id: project_id }.merge(data))
+        Resources::Epic.new({ project_id: project_id }.merge(data))
       end
     end
   end

data/lib/tracker_api/endpoints/epics.rb

@@ -12,7 +12,7 @@ module TrackerApi
         raise TrackerApi::Errors::UnexpectedData, 'Array of epics expected' unless data.is_a? Array
 
         data.map do |epic|
-          Resources::Epic.new({ client: client, project_id: project_id }.merge(epic))
+          Resources::Epic.new({ project_id: project_id }.merge(epic))
         end
       end
     end

data/lib/tracker_api/endpoints/me.rb

@@ -10,7 +10,7 @@ module TrackerApi
       def get
         data = client.get("/me").body
 
-        Resources::Me.new({ client: client }.merge(data))
+        Resources::Me.new(data)
       end
     end
   end

data/lib/tracker_api/endpoints/memberships.rb

@@ -12,7 +12,7 @@ module TrackerApi
         raise TrackerApi::Errors::UnexpectedData, 'Array of memberships expected' unless data.is_a? Array
 
         data.map do |membership|
-          Resources::ProjectMembership.new({ client: client, project_id: project_id }.merge(membership))
+          Resources::ProjectMembership.new({ project_id: project_id }.merge(membership))
         end
       end
     end

data/lib/tracker_api/endpoints/notifications.rb

@@ -0,0 +1,20 @@
+module TrackerApi
+  module Endpoints
+    class Notifications
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get(params={})
+        data = client.paginate('/my/notifications', params: params)
+        raise TrackerApi::Errors::UnexpectedData, 'Array of notifications expected' unless data.is_a? Array
+
+        data.map do |notification|
+          Resources::Notification.new({ client: client }.merge(notification))
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/endpoints/story.rb

@@ -24,6 +24,14 @@ module TrackerApi
 
         Resources::Story.new({ client: client }.merge(data))
       end
+
+      def update(story, params={})
+        raise ArgumentError, 'Valid story required to update.' unless story.instance_of?(Resources::Story)
+
+        data = client.put("/projects/#{story.project_id}/stories/#{story.id}", params: params).body
+
+        story.attributes = data
+      end
     end
   end
 end

data/lib/tracker_api/endpoints/tasks.rb

@@ -12,7 +12,7 @@ module TrackerApi
         raise TrackerApi::Errors::UnexpectedData, 'Array of tasks expected' unless data.is_a? Array
 
         data.map do |task|
-          Resources::Task.new({ client: client, project_id: project_id }.merge(task))
+          Resources::Task.new({ story_id: story_id }.merge(task))
         end
       end
     end

data/lib/tracker_api/resources/activity.rb

@@ -0,0 +1,24 @@
+module TrackerApi
+  module Resources
+    class Activity
+      include Virtus.model
+
+      attribute :client
+
+      attribute :kind, String
+      attribute :guid, String
+      attribute :project_version, Integer
+      attribute :message, String
+      attribute :highlight, String
+      attribute :changes, Array[TrackerApi::Resources::Change]
+      attribute :primary_resources, Array[TrackerApi::Resources::PrimaryResource]
+      attribute :project, TrackerApi::Resources::Project
+      attribute :performed_by, TrackerApi::Resources::Person
+      attribute :occurred_at, DateTime
+
+      def project=(data)
+        super.client = client
+      end
+    end
+  end
+end

data/lib/tracker_api/resources/base.rb

@@ -0,0 +1,71 @@
+require 'virtus'
+require 'active_support/concern'
+require 'active_model'
+
+module TrackerApi
+  module Resources
+    module Base
+      extend ActiveSupport::Concern
+
+      include ActiveModel::Model
+      include ActiveModel::Dirty
+
+      included do
+        include Virtus.model
+        include OverrideAttributes
+
+        attribute :id, Integer
+
+        def initialize(attrs)
+          super
+
+          # always reset dirty tracking on initialize
+          reset_changes
+        end
+
+        private
+
+        # @return [Hash] key value pairs for just the changed attributes with their new values.
+        def just_changes
+          # @see changes in ActiveModel::Dirty in active_model/dirty.rb
+          #     { attr => [original value, new value] }
+          changes.inject({}) do |h, (k, v)|
+            h[k] = v[1]; h;
+          end
+        end
+      end
+
+      module OverrideAttributes
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          def attribute(name, type, options = {})
+            define_attribute_methods name
+
+            attribute = super
+            create_writer_with_dirty_tracking(name)
+            attribute
+          end
+
+          private
+
+          def create_writer_with_dirty_tracking(name)
+            method_str = <<-RUBY
+              def #{name}=(value)
+                prev_value = #{name}
+                new_value  = value
+                if prev_value != new_value
+                  #{name}_will_change!
+                  new_value = super(value)
+                end
+                new_value
+              end
+            RUBY
+
+            class_eval method_str, __FILE__, __LINE__ + 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/resources/change.rb

@@ -0,0 +1,15 @@
+module TrackerApi
+  module Resources
+    class Change
+      include Virtus.model
+
+      attribute :change_type, String
+      attribute :id, Integer
+      attribute :kind, String
+      attribute :name, String
+      attribute :new_values, Hash
+      attribute :original_values, Hash
+      attribute :story_type, String
+    end
+  end
+end

data/lib/tracker_api/resources/epic.rb

@@ -3,8 +3,6 @@ module TrackerApi
     class Epic
       include Virtus.model
 
-      attribute :client
-
       attribute :id, Integer
       attribute :created_at, DateTime
       attribute :description, String

data/lib/tracker_api/resources/iteration.rb

@@ -15,6 +15,10 @@ module TrackerApi
       attribute :stories, [TrackerApi::Resources::Story]
       attribute :story_ids, [Integer]
       attribute :team_strength, Float
+
+      def stories=(data)
+        super.each { |s| s.client = client }
+      end
     end
   end
 end

data/lib/tracker_api/resources/me.rb

@@ -3,8 +3,6 @@ module TrackerApi
     class Me
       include Virtus.model
 
-      attribute :client
-
       attribute :id, Integer
       attribute :name, String
       attribute :initials, String

data/lib/tracker_api/resources/membership_summary.rb

@@ -3,8 +3,6 @@ module TrackerApi
     class MembershipSummary
       include Virtus.model
 
-      attribute :client
-
       attribute :id, Integer
       attribute :kind, String
       attribute :last_viewed_at, DateTime

data/lib/tracker_api/resources/notification.rb

@@ -0,0 +1,26 @@
+module TrackerApi
+  module Resources
+    class Notification
+      include Virtus.model
+
+      attribute :client
+
+      attribute :id, Integer
+      attribute :message, String
+      attribute :kind, String
+      attribute :project, TrackerApi::Resources::Project
+      attribute :story, TrackerApi::Resources::Story
+      attribute :performer, TrackerApi::Resources::Person
+      attribute :created_at, DateTime
+      attribute :updated_at, DateTime
+
+      def project=(data)
+        super.client = client
+      end
+
+      def story=(data)
+        super.client = client
+      end
+    end
+  end
+end

data/lib/tracker_api/resources/person.rb

@@ -3,8 +3,6 @@ module TrackerApi
     class Person
       include Virtus.model
 
-      attribute :client
-
       attribute :kind, String
       attribute :id, Integer
       attribute :name, String

data/lib/tracker_api/resources/primary_resource.rb

@@ -0,0 +1,13 @@
+module TrackerApi
+  module Resources
+    class PrimaryResource
+      include Virtus.model
+
+      attribute :id, Integer
+      attribute :kind, String
+      attribute :name, String
+      attribute :story_type, String
+      attribute :url, String
+    end
+  end
+end

data/lib/tracker_api/resources/project.rb

@@ -45,6 +45,7 @@ module TrackerApi
         @label_list ||= labels.collect(&:name).join(',')
       end
 
+      # @param [Hash] params
       # @return [Array[Epic]] epics associated with this project
       def epics(params={})
         raise ArgumentError, 'Expected @epics to be an Array' unless @epics.is_a? Array
@@ -57,11 +58,23 @@ module TrackerApi
       # @option params [String] :scope Restricts the state of iterations to return.
       #   If not specified, it defaults to all iterations including done.
       #   Valid enumeration values: done, current, backlog, current_backlog.
+      # @option params [Integer] :number The iteration to retrieve, starting at 1
       # @option params [Integer] :offset The offset of first iteration to return, relative to the
       #   set of iterations specified by 'scope', with zero being the first iteration in the scope.
       # @option params [Integer] :limit The number of iterations to return relative to the offset.
       # @return [Array[Iteration]] iterations associated with this project
       def iterations(params = {})
+        if params.include?(:number)
+          number = params[:number].to_i
+          raise ArgumentError, ':number must be > 0' unless number > 0
+
+          params = params.merge(auto_paginate: false, limit: 1)
+          params.delete(:number)
+
+          offset          = number - 1
+          params[:offset] = offset if offset > 0
+        end
+
         Endpoints::Iterations.new(client).get(id, params)
       end
 
@@ -81,18 +94,28 @@ module TrackerApi
         Endpoints::Stories.new(client).get(id, params)
       end
 
+      # @param [Hash] params
+      # @return [Array[ProjectMembership]] memberships of this project
       def memberships(params = {})
         Endpoints::Memberships.new(client).get(id, params)
       end
 
+      # Provides a list of all the activity performed on a project.
+      #
+      # @param [Hash] params
+      # @return [Array[Activity]]
+      def activity(params = {})
+        Endpoints::Activity.new(client).get_project(id, params)
+      end
+
       # @param [Fixnum] story_id id of story to get
-      # @return [Story] Story with given id
+      # @return [Story] story with given id
       def story(story_id)
         Endpoints::Story.new(client).get(id, story_id)
       end
 
-      # @param [Hash] hash of attributes to create the story
-      # @return [Story] Story with given id
+      # @param [Hash] params attributes to create the story with
+      # @return [Story] newly created Story
       def create_story(params)
         Endpoints::Story.new(client).create(id, params)
       end

data/lib/tracker_api/resources/project_membership.rb

@@ -3,8 +3,6 @@ module TrackerApi
     class ProjectMembership
       include Virtus.model
 
-      attribute :client
-
       attribute :id, Integer
       attribute :person_id, Integer
       attribute :project_id, Integer

data/lib/tracker_api/resources/story.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Story
-      include Virtus.model
+      include TrackerApi::Resources::Base
 
       attribute :client
 
@@ -14,13 +14,13 @@ module TrackerApi
       attribute :estimate, Float
       attribute :external_id, String
       attribute :follower_ids, Array[Integer]
-      attribute :id, Integer
       attribute :integration_id, Integer
       attribute :kind, String
       attribute :label_ids, Array[Integer]
       attribute :labels, Array[TrackerApi::Resources::Label]
       attribute :name, String
       attribute :owned_by_id, Integer # deprecated!
+      attribute :owner_ids, Array[Integer]
       attribute :owners, Array[TrackerApi::Resources::Person]
       attribute :planned_iteration_number, Integer
       attribute :project_id, Integer
@@ -36,6 +36,16 @@ module TrackerApi
         @label_list ||= labels.collect(&:name).join(',')
       end
 
+      # Provides a list of all the activity performed on the story.
+      #
+      # @param [Hash] params
+      # @return [Array[Activity]]
+      def activity(params = {})
+        Endpoints::Activity.new(client).get_story(project_id, id, params)
+      end
+
+      # @param [Hash] params
+      # @return [Array[Task]]
       def tasks(params = {})
         if @tasks.any?
           @tasks
@@ -43,6 +53,15 @@ module TrackerApi
           @tasks = Endpoints::Tasks.new(client).get(project_id, id, params)
         end
       end
+
+      # Save changes to an existing Story.
+      def save
+        raise ArgumentError, 'Can not update a story with an unknown project_id.' if project_id.nil?
+
+        Endpoints::Story.new(client).update(self, just_changes)
+
+        changes_applied
+      end
     end
   end
 end

data/lib/tracker_api/resources/task.rb

@@ -3,8 +3,6 @@ module TrackerApi
     class Task
       include Virtus.model
 
-      attribute :client
-
       attribute :id, Integer
       attribute :story_id, Integer
       attribute :description, String

data/lib/tracker_api/version.rb

@@ -1,3 +1,3 @@
 module TrackerApi
-  VERSION = '0.2.6'
+  VERSION = '0.2.7'
 end

data/lib/tracker_api.rb

@@ -20,11 +20,13 @@ module TrackerApi
   end
 
   module Endpoints
+    autoload :Activity, 'tracker_api/endpoints/activity'
     autoload :Epic, 'tracker_api/endpoints/epic'
     autoload :Epics, 'tracker_api/endpoints/epics'
     autoload :Iterations, 'tracker_api/endpoints/iterations'
     autoload :Me, 'tracker_api/endpoints/me'
     autoload :Memberships, 'tracker_api/endpoints/memberships'
+    autoload :Notifications, 'tracker_api/endpoints/notifications'
     autoload :Project, 'tracker_api/endpoints/project'
     autoload :Projects, 'tracker_api/endpoints/projects'
     autoload :Stories, 'tracker_api/endpoints/stories'
@@ -33,13 +35,18 @@ module TrackerApi
   end
 
   module Resources
+    autoload :Base, 'tracker_api/resources/base'
+    autoload :Activity, 'tracker_api/resources/activity'
     autoload :Account, 'tracker_api/resources/account'
+    autoload :Change, 'tracker_api/resources/change'
     autoload :Epic, 'tracker_api/resources/epic'
     autoload :Iteration, 'tracker_api/resources/iteration'
     autoload :Me, 'tracker_api/resources/me'
     autoload :MembershipSummary, 'tracker_api/resources/membership_summary'
+    autoload :Notification, 'tracker_api/resources/notification'
     autoload :Label, 'tracker_api/resources/label'
     autoload :Person, 'tracker_api/resources/person'
+    autoload :PrimaryResource, 'tracker_api/resources/primary_resource'
     autoload :Project, 'tracker_api/resources/project'
     autoload :ProjectMembership, 'tracker_api/resources/project_membership'
     autoload :Story, 'tracker_api/resources/story'

data/test/client_test.rb

@@ -86,7 +86,7 @@ describe TrackerApi::Client do
 
     it 'auto paginates when needed' do
       VCR.use_cassette('client: get all stories with pagination', record: :new_episodes) do
-        project = client.project(project_id)
+        project         = client.project(project_id)
 
         # skip pagination with a hugh limit
         unpaged_stories = project.stories(limit: 300)
@@ -136,4 +136,48 @@ describe TrackerApi::Client do
       end
     end
   end
+
+  describe '.notifictions' do
+    let(:pt_user) { PT_USER_1 }
+    let(:client) { TrackerApi::Client.new token: pt_user[:token] }
+
+    it 'gets authenticated persons notifications' do
+      VCR.use_cassette('get all notifications', record: :new_episodes) do
+        notifications = client.notifications
+
+        notifications.wont_be_empty
+        notification = notifications.first
+        notification.must_be_instance_of TrackerApi::Resources::Notification
+
+        notification.project.id.must_equal pt_user[:project_id]
+        notification.story.must_be_instance_of TrackerApi::Resources::Story
+        notification.performer.must_be_instance_of TrackerApi::Resources::Person
+      end
+    end
+  end
+
+  describe '.activity' do
+    let(:pt_user) { PT_USER_1 }
+    let(:client) { TrackerApi::Client.new token: pt_user[:token] }
+
+    it 'gets all my activities' do
+      VCR.use_cassette('get my activities', record: :new_episodes) do
+        activities = client.activity(fields: ':default')
+
+        activities.wont_be_empty
+        activity = activities.first
+        activity.must_be_instance_of TrackerApi::Resources::Activity
+
+        activity.changes.wont_be_empty
+        activity.changes.first.must_be_instance_of TrackerApi::Resources::Change
+
+        activity.primary_resources.wont_be_empty
+        activity.primary_resources.first.must_be_instance_of TrackerApi::Resources::PrimaryResource
+
+        activity.project.must_be_instance_of TrackerApi::Resources::Project
+
+        activity.performed_by.must_be_instance_of TrackerApi::Resources::Person
+      end
+    end
+  end
 end