harvesting 0.1.0 → 0.5.1

data/lib/harvesting.rb

@@ -1,16 +1,31 @@
+# framework
 require "harvesting/version"
 require "harvesting/enumerable"
 require "harvesting/errors"
 require "harvesting/models/base"
-require "harvesting/models/user"
-require "harvesting/models/contact"
+require "harvesting/models/harvest_record"
+require "harvesting/models/harvest_record_collection"
+# harvest records
 require "harvesting/models/client"
-require "harvesting/models/projects"
+require "harvesting/models/user"
 require "harvesting/models/project"
-require "harvesting/models/tasks"
 require "harvesting/models/task"
-require "harvesting/models/time_entries"
+require "harvesting/models/project_user_assignment"
+require "harvesting/models/project_task_assignment"
+require "harvesting/models/invoice"
+require "harvesting/models/line_item"
 require "harvesting/models/time_entry"
+# harvest record collections
+require "harvesting/models/clients"
+require "harvesting/models/tasks"
+require "harvesting/models/users"
+require "harvesting/models/contact"
+require "harvesting/models/time_entries"
+require "harvesting/models/projects"
+require "harvesting/models/project_user_assignments"
+require "harvesting/models/project_task_assignments"
+require "harvesting/models/invoices"
+# API client
 require "harvesting/client"
 
 module Harvesting

data/lib/harvesting/client.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
-
-require "byebug"
 require "http"
 require "json"
 
 module Harvesting
+
+  # A client for the Harvest API (version 2.0)
   class Client
     DEFAULT_HOST = "https://api.harvestapp.com/v2"
 
     attr_accessor :access_token, :account_id
 
+    # Returns a new instance of `Client`
     #
-    # @param opts
+    #     client = Client.new(access_token: "12345678", account_id: "98764")
     #
+    # @param [Hash] opts the options to create an API client
+    # @option opts [String] :access_token Harvest access token
+    # @option opts [String] :account_id Harvest account id
     def initialize(access_token: ENV['HARVEST_ACCESS_TOKEN'], account_id: ENV['HARVEST_ACCOUNT_ID'])
       @access_token = access_token.to_s
       @account_id = account_id.to_s
@@ -22,34 +26,66 @@ module Harvesting
       end
     end
 
+    # @return [Harvesting::Models::User]
     def me
-      Harvesting::Models::User.new(get("users/me"), client: self)
+      Harvesting::Models::User.new(get("users/me"), harvest_client: self)
     end
-
-    def clients
-      get("clients")["clients"].map do |result|
-        Harvesting::Models::Client.new(result, client: self)
-      end
+    
+    # @return [Harvesting::Models::Clients]
+    def clients(opts = {})
+      Harvesting::Models::Clients.new(get("clients", opts), opts, harvest_client: self)
     end
 
+    # @return [Array<Harvesting::Models::Contact>]
     def contacts
       get("contacts")["contacts"].map do |result|
-        Harvesting::Models::Contact.new(result, client: self)
+        Harvesting::Models::Contact.new(result, harvest_client: self)
       end
     end
 
+    # @return [Harvesting::Models::TimeEntries]
     def time_entries(opts = {})
-      Harvesting::Models::TimeEntries.new(get("time_entries", opts), client: self)
+      Harvesting::Models::TimeEntries.new(get("time_entries", opts), opts, harvest_client: self)
     end
 
+    # @return [Harvesting::Models::Projects]
     def projects(opts = {})
-      Harvesting::Models::Projects.new(get("projects", opts), client: self)
+      Harvesting::Models::Projects.new(get("projects", opts), opts, harvest_client: self)
     end
 
+    # @return [Harvesting::Models::Tasks]
     def tasks(opts = {})
-      Harvesting::Models::Tasks.new(get("tasks", opts), client: self)
+      Harvesting::Models::Tasks.new(get("tasks", opts), opts, harvest_client: self)
+    end
+
+    # @return [Harvesting::Models::Users]
+    def users(opts = {})
+      Harvesting::Models::Users.new(get("users", opts), opts, harvest_client: self)
+    end
+
+    # @return [Array<Harvesting::Models::Invoice>]
+    def invoices(opts = {})
+      Harvesting::Models::Invoices.new(get("invoices", opts), opts, harvest_client: self)
+    end
+
+    # @return [Harvesting::Models::ProjectUserAssignments]
+    def user_assignments(opts = {})
+      project_id = opts.delete(:project_id)
+      path = project_id.nil? ? "user_assignments" : "projects/#{project_id}/user_assignments"
+      Harvesting::Models::ProjectUserAssignments.new(get(path, opts), opts, harvest_client: self)
+    end
+
+    # @return [Harvesting::Models::ProjectTaskAssignments]
+    def task_assignments(opts = {})
+      project_id = opts.delete(:project_id)
+      path = project_id.nil? ? "task_assignments" : "projects/#{project_id}/task_assignments"
+      Harvesting::Models::ProjectTaskAssignments.new(get(path, opts), opts, harvest_client: self)
     end
 
+    # Creates an `entity` in your Harvest account.
+    #
+    # @param entity [Harvesting::Models::Base] A new record in your Harvest account
+    # @return [Harvesting::Models::Base] A subclass of `Harvesting::Models::Base` updated with the response from Harvest
     def create(entity)
       url = "#{DEFAULT_HOST}/#{entity.path}"
       uri = URI(url)
@@ -58,6 +94,10 @@ module Harvesting
       entity
     end
 
+    # Updates an `entity` in your Harvest account.
+    #
+    # @param entity [Harvesting::Models::Base] An existing record in your Harvest account
+    # @return [Harvesting::Models::Base] A subclass of `Harvesting::Models::Base` updated with the response from Harvest
     def update(entity)
       url = "#{DEFAULT_HOST}/#{entity.path}"
       uri = URI(url)
@@ -66,8 +106,25 @@ module Harvesting
       entity
     end
 
-    private
+    # It removes an `entity` from your Harvest account.
+    #
+    # @param entity [Harvesting::Models::Base] A record to be removed from your Harvest account
+    # @return [Hash]
+    # @raise [UnprocessableRequest] When HTTP response is not 200 OK
+    def delete(entity)
+      url = "#{DEFAULT_HOST}/#{entity.path}"
+      uri = URI(url)
+      response = http_response(:delete, uri)
+      raise UnprocessableRequest.new(response.to_s) unless response.code.to_i == 200
+      
+      JSON.parse(response.body)
+    end
 
+    # Performs a GET request and returned the parsed JSON as a Hash.
+    #
+    # @param path [String] path to be combined with `DEFAULT_HOST`
+    # @param opts [Hash] key/values will get passed as HTTP (GET) parameters
+    # @return [Hash]
     def get(path, opts = {})
       url = "#{DEFAULT_HOST}/#{path}"
       url += "?#{opts.map {|k, v| "#{k}=#{v}"}.join("&")}" if opts.any?
@@ -76,10 +133,12 @@ module Harvesting
       JSON.parse(response.body)
     end
 
+    private
+
     def http_response(method, uri, opts = {})
       response = nil
 
-      http = HTTP["User-Agent" => "Ruby Harvest API Sample",
+      http = HTTP["User-Agent" => "Harvesting Ruby Gem",
                   "Authorization" => "Bearer #{@access_token}",
                   "Harvest-Account-ID" => @account_id]
       params = {}
@@ -90,6 +149,8 @@ module Harvesting
 
       raise Harvesting::AuthenticationError.new(response.to_s) if auth_error?(response)
       raise Harvesting::UnprocessableRequest.new(response.to_s) if response.code.to_i == 422
+      raise Harvesting::RequestNotFound.new(uri) if response.code.to_i == 404
+      raise Harvesting::RateLimitExceeded.new(response.to_s) if response.code.to_i == 429
 
       response
     end

data/lib/harvesting/enumerable.rb

@@ -1,10 +1,13 @@
+# `Enumerable` extends the stdlib `Enumerable` to provide pagination for paged
+# API requests.
+#
 # @see https://github.com/sferik/twitter/blob/aa909b3b7733ca619d80f1c8cba961033d1fc7e6/lib/twitter/enumerable.rb
 module Harvesting
   module Enumerable
     include ::Enumerable
 
     # @return [Enumerator]
-    def each(start = 0)
+    def each(start = 0, &block)
       @cursor = start
       return to_enum(:each, start) unless block_given?
       Array(@entries[start..-1]).each_with_index do |element, index|
@@ -15,7 +18,7 @@ module Harvesting
       unless last?
         start = [@entries.size, start].max
         fetch_next_page
-        each(start, &Proc.new)
+        each(start, &block)
       end
       self
     end

data/lib/harvesting/errors.rb

@@ -4,4 +4,13 @@ module Harvesting
 
   class UnprocessableRequest < StandardError
   end
+
+  class RequestNotFound < StandardError
+    def initialize(uri)
+      super("The page you were looking for may have been moved or the address misspelled: #{uri}")
+    end
+  end
+
+  class RateLimitExceeded < StandardError
+  end
 end

data/lib/harvesting/models/base.rb

@@ -1,37 +1,118 @@
 module Harvesting
   module Models
     class Base
+      # @return [Hash]
       attr_accessor :attributes
-      attr_reader :client
+      # @return [Harvesting::Model::Client]
+      attr_reader :harvest_client
 
       def initialize(attrs, opts = {})
+        @models = {}
         @attributes = attrs.dup
-        @client = opts[:client] || Harvesting::Client.new(opts)
-      end
-
-      def self.attributed(*attribute_names)
-        attribute_names.each do |attribute_name|
-          Harvesting::Models::Base.send :define_method, attribute_name.to_s do
-            @attributes[__method__.to_s]
-          end
-        end
+        @harvest_client = opts[:harvest_client] || Harvesting::Client.new(opts)
       end
 
+      # It calls `create` or `update` depending on the record's ID. If the ID
+      # is present, then it calls `update`. Otherwise it calls `create`
+      #
+      # @see Client#create
+      # @see Client#update
       def save
         id.nil? ? create : update
       end
 
+      # It creates the record.
+      #
+      # @see Client#create
+      # @return [Harvesting::Models::Base]
       def create
-        @client.create(self)
+        @harvest_client.create(self)
       end
 
+      # It updates the record.
+      #
+      # @see Client#update
+      # @return [Harvesting::Models::Base]
       def update
-        @client.update(self)
+        @harvest_client.update(self)
       end
 
+      # It removes the record.
+      #
+      # @see Client#delete
+      # @return [Harvesting::Models::Base]
+      def delete
+        @harvest_client.delete(self)
+      end
+
+      # It returns keys and values for all the attributes of this record.
+      #
+      # @return [Hash]
       def to_hash
         @attributes
       end
+
+      # It loads a new record from your Harvest account.
+      #
+      # @return [Harvesting::Models::Base]
+      def fetch
+        self.class.new(@harvest_client.get(path), harvest_client: @harvest_client)
+      end
+
+      # Retrieves an instance of the object by ID
+      #
+      # @param id [Integer] the id of the object to retrieve
+      # @param opts [Hash] options to pass along to the `Harvesting::Client`
+      #   instance
+      def self.get(id, opts = {})
+        client = opts[:harvest_client] || Harvesting::Client.new(opts)
+        self.new({ 'id' => id }, opts).fetch
+      end
+
+      protected
+
+      # Class method to define attribute methods for accessing attributes for
+      # a record
+      #
+      # It needs to be used like this:
+      #
+      #     class Contact < HarvestRecord
+      #       attributed :id,
+      #                  :title,
+      #                  :first_name
+      #       ...
+      #     end
+      #
+      # @param attribute_names [Array] A list of attributes
+      def self.attributed(*attribute_names)
+        attribute_names.each do |attribute_name|
+          define_method(attribute_name) do
+            @attributes[__method__.to_s]
+          end
+          define_method("#{attribute_name}=") do |value|
+            @attributes[__method__.to_s.chop] = value
+          end
+        end
+      end
+
+      # Class method to define nested resources for a record.
+      #
+      # It needs to be used like this:
+      #
+      #     class Contact < HarvestRecord
+      #       modeled client: Client
+      #       ...
+      #     end
+      #
+      # @param opts [Hash] key = symbol that needs to be the same as the one returned by the Harvest API. value = model class for the nested resource.
+      def self.modeled(opts = {})
+        opts.each do |attribute_name, model|
+          attribute_name_string = attribute_name.to_s
+          Harvesting::Models::Base.send :define_method, attribute_name_string do
+            @models[attribute_name_string] ||= model.new(@attributes[attribute_name_string] || {}, harvest_client: harvest_client)
+          end
+        end
+      end
     end
   end
 end

data/lib/harvesting/models/client.rb

@@ -1,6 +1,9 @@
 module Harvesting
   module Models
-    class Client < Base
+    # A client record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/clients-api/clients/clients/
+    class Client < HarvestRecord
       attributed :id,
                  :name,
                  :is_active,
@@ -9,6 +12,9 @@ module Harvesting
                  :updated_at,
                  :currency
 
+      def path
+        @attributes['id'].nil? ? "clients" : "clients/#{@attributes['id']}"
+      end
     end
   end
 end

data/lib/harvesting/models/clients.rb

@@ -0,0 +1,18 @@
+module Harvesting
+  module Models
+    class Clients < HarvestRecordCollection
+
+      def initialize(attrs, query_opts = {}, opts = {})
+        super(attrs.reject {|k,v| k == "clients" }, query_opts, opts)
+        @entries = attrs["clients"].map do |entry|
+          Harvesting::Models::Client.new(entry, harvest_client: opts[:harvest_client])
+        end
+      end
+
+      def fetch_next_page
+        @entries += harvest_client.clients(next_page_query_opts).entries
+        @attributes['page'] = page + 1
+      end
+    end
+  end
+end

data/lib/harvesting/models/contact.rb

@@ -1,6 +1,9 @@
 module Harvesting
   module Models
-    class Contact < Base
+    # A contact record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/clients-api/clients/contacts/
+    class Contact < HarvestRecord
       attributed :id,
                  :title,
                  :first_name,
@@ -11,6 +14,16 @@ module Harvesting
                  :fax,
                  :created_at,
                  :updated_at
+
+      modeled client: Client
+
+      def path
+        @attributes['id'].nil? ? "contacts" : "contacts/#{@attributes['id']}"
+      end
+      
+      def to_hash
+        { client_id: client.id }.merge(super)
+      end
     end
   end
 end

data/lib/harvesting/models/harvest_record.rb

@@ -0,0 +1,18 @@
+module Harvesting
+  module Models
+    class HarvestRecord < Base
+
+      def save
+        id.nil? ? create : update
+      end
+
+      def create
+        harvest_client.create(self)
+      end
+
+      def update
+        harvest_client.update(self)
+      end
+    end
+  end
+end