tracker_api 0.2.12 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4ea13ce0c74d3e644ebc7425d5100931b0e1e3a
-  data.tar.gz: 4e5e624540678a7a39757ce74b102e3300dbce8d
+  metadata.gz: 3fbc8caee5a56cdf59e58fc545d0390f76685dc2
+  data.tar.gz: cae843ef9bdc193e763d440db310a79e9fb7fe4a
 SHA512:
-  metadata.gz: 9356f13e4620b8a7c420b52a2beba5bbd29ef6a921882df0edc0e612d8b77886869a964a1a723fc6b4bc8d73d0eb9f74a0dafd0737f54b40dec8cc3d9a816abe
-  data.tar.gz: 199de08b674ddd887ece1a3f8d30e8be802723185554f70fdacc9dc74c3031c1fd3963b4beaa2c44ad7f61fc685e8f2f6d33874c6b24b90b65baa8bfc211e1e8
+  metadata.gz: 81a23229a778910df741e89fea770bec3096cadeb85c40dc9f79b587fc8fa1e6617c4e853f7f0722d6eb6037162276d49a6f6132e0501a8dfd0fdd1aa6db2e58
+  data.tar.gz: 5be684a973dd96a30c032fd50179790505bab01ba8be8a61d0fb7b9a9bd30ec8a25bb697b8836764f116e7c0070f130d21d69f548e7e80c67ea171c19e4da36c

data/.gitignore

@@ -17,3 +17,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.byebug_history

data/README.md

@@ -53,7 +53,7 @@ story.activity                                                            # Get
 
 story.name = 'Save the Ewoks'                                             # Update a single story attribute
 story.attributes = { name: 'Save the Ewoks', description: '...' }         # Update multiple story attributes
-story.labels << TrackerApi::Resources::Label.new(name: 'Endor')           # Add a new label to an existing story
+story.add_label('Endor')                                                  # Add a new label to an existing story
 story.save                                                                # Save changes made to a story
 
 story = TrackerApi::Resources::Story.new( client:     client,

data/lib/tracker_api.rb

@@ -1,17 +1,18 @@
 require 'tracker_api/version'
 
 # dependencies
-require 'virtus'
 require 'faraday'
 require 'faraday_middleware'
+
 if defined?(ActiveSupport)
   require 'active_support/core_ext/object/blank'
 else
   require 'core_ext/object/blank'
 end
 require 'equalizer'
-require 'representable/json'
+
 require 'multi_json'
+require 'representable/json'
 
 # stdlib
 require 'addressable/uri'
@@ -51,7 +52,8 @@ module TrackerApi
 
   module Resources
     module Shared
-      autoload :HasId, 'tracker_api/resources/shared/has_id'
+      autoload :Base, 'tracker_api/resources/shared/base'
+      autoload :Collection, 'tracker_api/resources/shared/collection'
     end
     autoload :Activity, 'tracker_api/resources/activity'
     autoload :Account, 'tracker_api/resources/account'

data/lib/tracker_api/client.rb

@@ -138,9 +138,19 @@ module TrackerApi
     # Get information about a client story without knowing what project the story belongs to
     #
     # @param [String] story_id
+    # @param [Hash] params
     # @return [TrackerApi::Resources::Story]
-    def story(story_id)
-      Endpoints::Story.new(self).get_story(story_id)
+    def story(story_id, params={})
+      Endpoints::Story.new(self).get_story(story_id, params)
+    end
+
+    # Get information about an epic without knowing what project the epic belongs to
+    #
+    # @param [String] epic_id
+    # @param [Hash] params
+    # @return [TrackerApi::Resources::Epic]
+    def epic(epic_id, params={})
+      Endpoints::Epic.new(self).get_epic(epic_id, params)
     end
 
     # Get notifications for the authenticated person

data/lib/tracker_api/endpoints/epic.rb

@@ -13,6 +13,12 @@ module TrackerApi
         Resources::Epic.new({ client: client, project_id: project_id }.merge(data))
       end
 
+      def get_epic(epic_id, params={})
+        data = client.get("/epics/#{epic_id}", params: params).body
+
+        Resources::Epic.new({ client: client }.merge(data))
+      end
+
       def create(project_id, params={})
         data = client.post("/projects/#{project_id}/epics", params: params).body
 
@@ -25,6 +31,8 @@ module TrackerApi
         data = client.put("/projects/#{epic.project_id}/epics/#{epic.id}", params: params).body
 
         epic.attributes = data
+        epic.clean!
+        epic
       end
     end
   end

data/lib/tracker_api/endpoints/story.rb

@@ -31,6 +31,8 @@ module TrackerApi
         data = client.put("/projects/#{story.project_id}/stories/#{story.id}", params: params).body
 
         story.attributes = data
+        story.clean!
+        story
       end
     end
   end

data/lib/tracker_api/resources/account.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Account
-      include Shared::HasId
+      include Shared::Base
 
       attribute :created_at, DateTime
       attribute :status, String

data/lib/tracker_api/resources/activity.rb

@@ -11,8 +11,8 @@ module TrackerApi
       attribute :project_version, Integer
       attribute :message, String
       attribute :highlight, String
-      attribute :changes, Array[Change]
-      attribute :primary_resources, Array[PrimaryResource]
+      attribute :changes, Shared::Collection[Change]
+      attribute :primary_resources, Shared::Collection[PrimaryResource]
       attribute :project, Project
       attribute :performed_by, Person
       attribute :occurred_at, DateTime

data/lib/tracker_api/resources/change.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Change
-      include Shared::HasId
+      include Shared::Base
 
       attribute :change_type, String
       attribute :kind, String

data/lib/tracker_api/resources/comment.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Comment
-      include Shared::HasId
+      include Shared::Base
 
       attribute :story_id, Integer
       attribute :epic_id, Integer
@@ -9,11 +9,11 @@ module TrackerApi
       attribute :person_id, Integer
       attribute :created_at, DateTime
       attribute :updated_at, DateTime
-      attribute :file_attachment_ids, Array[Integer]
-      attribute :google_attachment_ids, Array[Integer]
+      attribute :file_attachment_ids, Shared::Collection[Integer]
+      attribute :google_attachment_ids, Shared::Collection[Integer]
       attribute :commit_identifier, String
       attribute :commit_type, String
       attribute :kind, String
     end
   end
-end
+end

data/lib/tracker_api/resources/epic.rb

@@ -1,16 +1,16 @@
 module TrackerApi
   module Resources
     class Epic
-      include Shared::HasId
+      include Shared::Base
 
       attribute :client
 
-      attribute :comment_ids, Array[Integer]
-      attribute :comments, Array[Comment]
+      attribute :comment_ids, Shared::Collection[Integer]
+      attribute :comments, Shared::Collection[Comment]
       attribute :created_at, DateTime
       attribute :description, String
-      attribute :follower_ids, Array[Integer]
-      attribute :followers, Array[Person]
+      attribute :follower_ids, Shared::Collection[Integer]
+      attribute :followers, Shared::Collection[Person]
       attribute :kind, String
       attribute :label, Label
       attribute :label_id, Integer

data/lib/tracker_api/resources/iteration.rb

@@ -13,8 +13,8 @@ module TrackerApi
       attribute :planned, Boolean
       attribute :project_id, Integer
       attribute :start, DateTime
-      attribute :stories, [Story]
-      attribute :story_ids, [Integer]
+      attribute :stories, Shared::Collection[Story]
+      attribute :story_ids, Shared::Collection[Integer]
       attribute :team_strength, Float
 
       def stories=(data)

data/lib/tracker_api/resources/label.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Label
-      include Shared::HasId
+      include Shared::Base
 
       attribute :created_at, DateTime
       attribute :kind, String

data/lib/tracker_api/resources/me.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Me
-      include Shared::HasId
+      include Shared::Base
 
       attribute :name, String
       attribute :initials, String
@@ -9,9 +9,9 @@ module TrackerApi
       attribute :time_zone, TimeZone
       attribute :api_token, String
       attribute :has_google_identity, Boolean
-      attribute :project_ids, Array[Integer]
-      attribute :projects, [MembershipSummary]
-      attribute :workspace_ids, Array[Integer]
+      attribute :project_ids, Shared::Collection[Integer]
+      attribute :projects, Shared::Collection[MembershipSummary]
+      attribute :workspace_ids, Shared::Collection[Integer]
       attribute :email, String
       attribute :receives_in_app_notifications, Boolean
       attribute :kind, String

data/lib/tracker_api/resources/membership_summary.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class MembershipSummary
-      include Shared::HasId
+      include Shared::Base
 
       attribute :kind, String
       attribute :last_viewed_at, DateTime

data/lib/tracker_api/resources/notification.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Notification
-      include Shared::HasId
+      include Shared::Base
 
       attribute :client
 

data/lib/tracker_api/resources/person.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Person
-      include Shared::HasId
+      include Shared::Base
 
       attribute :kind, String
       attribute :name, String

data/lib/tracker_api/resources/primary_resource.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class PrimaryResource
-      include Shared::HasId
+      include Shared::Base
 
       attribute :kind, String
       attribute :name, String

data/lib/tracker_api/resources/project.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class Project
-      include Shared::HasId
+      include Shared::Base
 
       attribute :client
 
@@ -17,14 +17,14 @@ module TrackerApi
       attribute :enable_incoming_emails, Boolean
       attribute :enable_planned_mode, Boolean
       attribute :enable_tasks, Boolean
-      attribute :epic_ids, Array[Integer]
-      attribute :epics, Array[Epic]
+      attribute :epic_ids, Shared::Collection[Integer]
+      attribute :epics, Shared::Collection[Epic]
       attribute :has_google_domain, Boolean
       attribute :initial_velocity, Integer
       attribute :iteration_length, Integer
       attribute :kind, String
-      attribute :label_ids, Array[Integer]
-      attribute :labels, Array[Label]
+      attribute :label_ids, Shared::Collection[Integer]
+      attribute :labels, Shared::Collection[Label]
       attribute :name, String
       attribute :number_of_done_iterations_to_show, Integer
       attribute :point_scale, String
@@ -54,7 +54,7 @@ module TrackerApi
       # @param [Hash] params
       # @return [Array[Label]] labels of this project
       def labels(params = {})
-        if @labels && @labels.any?
+        if @labels && @labels.present?
           @labels
         else
           @labels = Endpoints::Labels.new(client).get(id, params)
@@ -66,10 +66,11 @@ module TrackerApi
       # @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
-        return @epics unless @epics.empty?
-
-        @epics = Endpoints::Epics.new(client).get(id, params)
+        if @epics && @epics.present?
+          @epics
+        else
+          @epics = Endpoints::Epics.new(client).get(id, params)
+        end
       end
 
       # Provides a list of all the iterations in the project.

data/lib/tracker_api/resources/project_membership.rb

@@ -1,7 +1,7 @@
 module TrackerApi
   module Resources
     class ProjectMembership
-      include Shared::HasId
+      include Shared::Base
 
       attribute :person_id, Integer
       attribute :project_id, Integer

data/lib/tracker_api/resources/shared/base.rb

@@ -0,0 +1,30 @@
+require 'virtus'
+if Virtus::Attribute::NullifyBlank.method_defined?(:coerce)
+  require 'virtus/attribute/nullify_blank'
+else
+  raise """
+  WARNING: The above monkey patch can't be applied as expected.
+  See discussion here: https://github.com/dashofcode/tracker_api/commit/27599e7e2169776c32bbff8c972a31b930452879
+  """
+end
+require 'virtus/dirty_attribute'
+
+module TrackerApi
+  module Resources
+    module Shared
+      module Base
+        def self.included(base)
+          base.class_eval do
+            include Virtus.model(nullify_blank: true)
+            include Virtus::DirtyAttribute
+            include Virtus::DirtyAttribute::InitiallyClean
+
+            include Equalizer.new(:id)
+
+            attribute :id, Integer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/resources/shared/collection.rb

@@ -0,0 +1,17 @@
+module TrackerApi
+  module Resources
+    module Shared
+      class Collection < Array
+        def <<(item)
+          warn """
+            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.
+            https://github.com/solnic/virtus#important-note-about-member-coercions
+            """
+          super
+        end
+      end
+    end
+  end
+end

data/lib/tracker_api/resources/story.rb

@@ -1,37 +1,37 @@
 module TrackerApi
   module Resources
     class Story
-      include Shared::HasId
+      include Shared::Base
 
       attribute :client
 
       attribute :accepted_at, DateTime
-      attribute :comment_ids, Array[Integer]
-      attribute :comments, Array[Comment], :default => []
+      attribute :comment_ids, Shared::Collection[Integer]
+      attribute :comments, Shared::Collection[Comment]
       attribute :created_at, DateTime
       attribute :current_state, String # (accepted, delivered, finished, started, rejected, planned, unstarted, unscheduled)
       attribute :deadline, DateTime
       attribute :description, String
       attribute :estimate, Float
       attribute :external_id, String
-      attribute :follower_ids, Array[Integer]
-      attribute :followers, Array[Person]
+      attribute :follower_ids, Shared::Collection[Integer]
+      attribute :followers, Shared::Collection[Person]
       attribute :integration_id, Integer
       attribute :kind, String
-      attribute :label_ids, Array[Integer]
-      attribute :labels, Array[Label], :default => []
+      attribute :label_ids, Shared::Collection[Integer]
+      attribute :labels, Shared::Collection[Label]
       attribute :name, String
       attribute :owned_by_id, Integer # deprecated!
       attribute :owned_by, Person
-      attribute :owner_ids, Array[Integer]
-      attribute :owners, Array[Person], :default => []
+      attribute :owner_ids, Shared::Collection[Integer]
+      attribute :owners, Shared::Collection[Person]
       attribute :planned_iteration_number, Integer
       attribute :project_id, Integer
       attribute :requested_by, Person
       attribute :requested_by_id, Integer
       attribute :story_type, String # (feature, bug, chore, release)
-      attribute :task_ids, Array[Integer]
-      attribute :tasks, Array[Task], :default => []
+      attribute :task_ids, Shared::Collection[Integer]
+      attribute :tasks, Shared::Collection[Task]
       attribute :updated_at, DateTime
       attribute :url, String
 
@@ -39,7 +39,7 @@ module TrackerApi
       class UpdateRepresenter < Representable::Decorator
         include Representable::JSON
 
-        property :follower_ids
+        property :follower_ids, if: ->(options) { !options[:input].blank? }
         property :name
         property :description
         property :story_type
@@ -48,7 +48,7 @@ module TrackerApi
         property :accepted_at
         property :deadline
         property :requested_by_id
-        property :owner_ids
+        property :owner_ids, if: ->(options) { !options[:input].blank? }
         collection :labels, class: Label, decorator: Label::UpdateRepresenter, render_empty: true
         property :integration_id
         property :external_id
@@ -59,6 +59,20 @@ module TrackerApi
         @label_list ||= labels.collect(&:name).join(',')
       end
 
+      # Adds a new label to the story.
+      #
+      # @param [Label|Hash|String] label
+      def add_label(label)
+        new_label = if label.kind_of?(String)
+          Label.new(name: label)
+        else
+          label
+        end
+
+        # Use attribute writer to get coercion and dirty tracking.
+        self.labels = @labels.dup.push(new_label)
+      end
+
       # Provides a list of all the activity performed on the story.
       #
       # @param [Hash] params
@@ -72,7 +86,7 @@ module TrackerApi
       # @param [Hash] params
       # @return [Array[Comment]]
       def comments(params = {})
-        if params.blank? && @comments.any?
+        if params.blank? && @comments.present?
           @comments
         else
           @comments = Endpoints::Comments.new(client).get(project_id, id, params)
@@ -84,7 +98,7 @@ module TrackerApi
       # @param [Hash] params
       # @return [Array[Task]]
       def tasks(params = {})
-        if params.blank? && @tasks.any?
+        if params.blank? && @tasks.present?
           @tasks
         else
           @tasks = Endpoints::Tasks.new(client).get(project_id, id, params)
@@ -96,7 +110,7 @@ module TrackerApi
       # @param [Hash] params
       # @return [Array[Person]]
       def owners(params = {})
-        if params.blank? && @owners.any?
+        if params.blank? && @owners.present?
           @owners
         else
           @owners = Endpoints::StoryOwners.new(client).get(project_id, id, params)
@@ -113,7 +127,7 @@ module TrackerApi
       def save
         raise ArgumentError, 'Can not update a story with an unknown project_id.' if project_id.nil?
 
-        Endpoints::Story.new(client).update(self, UpdateRepresenter.new(self))
+        Endpoints::Story.new(client).update(self, UpdateRepresenter.new(Story.new(self.dirty_attributes)))
       end
     end
   end