harvesting 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 420911f1f064b300fb9db0e3490a23cee246fd1e8f885ac631558818a9afa761
-  data.tar.gz: cbf6caa05a4092e344e1638dab33081478a973282d3d1a9f2ed3cb30ec75f7ab
+  metadata.gz: 4452c68eed7a6097355f504450d77cf13e72424ca0ec6915fb041dd8abb155f7
+  data.tar.gz: 82e16401985e4e19cd14ac1fb57f13b9f87f2d29188800e584516a68c3412ca7
 SHA512:
-  metadata.gz: 3b9a22eb96ff64f1f0947b22d026311635419b29616e56a01baca381fac7ff0d61cbe1ff29597d24d461fb1a58d92db4edf755ac7c5ac206b71002e5bc3442f7
-  data.tar.gz: 398e22c481a9f56e543beebb87a0b0572e725e8f2dd5eb61ea78176bec5f56d6afac652e1a9477754eb608fc612fe45d212fed8fb2034e1724997cce017855a1
+  metadata.gz: cf1b81f56a3ec9c5efc9c19816ea6da487927fc00f49d255e58f647d918de5e9ce5a54b5e6bf1c848fb0002e3239f1d25590720acaf0c84bbbc12247ef634b84
+  data.tar.gz: a40d1ec6516ef528129aedc4747943189c19b3da0b5cf4ac950be1e735c06814008a192a303d2cf9a2f93b0336d0fae988be72fcaa8f5d1953511453a08b1a0d

data/.env.sample

@@ -1,7 +1,10 @@
-HARVEST_FIRST_NAME=John
-HARVEST_LAST_NAME=Smith
+HARVEST_FIRST_NAME=<replace me with a test account>
+HARVEST_LAST_NAME=<replace me with a test account>
 HARVEST_ACCOUNT_ID=<replace me with a test account>
 HARVEST_NON_ADMIN_ACCOUNT_ID=<replace me with a test account>
 HARVEST_ACCESS_TOKEN=<replace me with a test account>
 HARVEST_NON_ADMIN_ACCESS_TOKEN=<replace me with a test account>
 HARVEST_ADMIN_FULL_NAME=<replace me with a test account>
+HARVEST_NON_ADMIN_FULL_NAME=<replace me with a test account>
+HARVEST_ADMIN_FIRST_NAME=<replace me with a test account>
+HARVEST_ADMIN_LAST_NAME=<replace me with a test account>

data/.gitignore

@@ -9,6 +9,9 @@
 
 # environment variables
 .env
+.env.*
+!.env.sample
+
 
 # rspec failure tracking
 .rspec_status
@@ -24,3 +27,5 @@
 
 .idea/
 harvesting.iml
+
+.DS_Store

data/.travis.yml

@@ -2,4 +2,8 @@ sudo: false
 language: ruby
 rvm:
   - 2.4.1
-before_install: gem install bundler -v 1.16.1
+  - 2.5.1
+env:
+  - HARVEST_FIRST_NAME=Aaron HARVEST_LAST_NAME=Burr HARVEST_ACCOUNT_ID=112341234 HARVEST_NON_ADMIN_ACCOUNT_ID=112341234 HARVEST_ACCESS_TOKEN=112341234 HARVEST_NON_ADMIN_ACCESS_TOKEN=112341234 HARVEST_ADMIN_FULL_NAME=112341234
+
+before_install: gem install bundler -v 1.17.3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    harvesting (0.2.0)
+    harvesting (0.3.0)
       http (~> 3.3, >= 3.3)
 
 GEM
@@ -17,7 +17,7 @@ GEM
     domain_name (0.5.20180417)
       unf (>= 0.0.5, < 1.0.0)
     dotenv (2.5.0)
-    ffi (1.9.23)
+    ffi (1.12.2)
     formatador (0.2.5)
     guard (2.14.2)
       formatador (>= 0.2.4)
@@ -57,7 +57,7 @@ GEM
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     public_suffix (3.0.2)
-    rake (10.5.0)
+    rake (13.0.1)
     rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
@@ -96,10 +96,10 @@ DEPENDENCIES
   dotenv (~> 2.5, >= 2.5)
   guard-rspec (~> 4.7, >= 4.7)
   harvesting!
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.0)
   vcr (~> 4.0, >= 4.0)
   webmock (~> 3.4, >= 3.4)
 
 BUNDLED WITH
-   1.16.1
+   1.17.2

data/README.md

@@ -1,5 +1,8 @@
 # Harvesting
 
+[![Build Status](https://travis-ci.org/ombulabs/harvesting.svg?branch=master)](https://travis-ci.org/ombulabs/harvesting)
+[![Code Climate](https://codeclimate.com/github/ombulabs/harvesting/badges/gpa.svg)](https://codeclimate.com/github/ombulabs/harvesting)
+
 A Ruby gem to interact with the Harvest API v2.0 and forward.
 
 ## Installation
@@ -39,69 +42,103 @@ to these environment variables:
 
 That means that you could build a client like this:
 
-    # $ export HARVEST_ACCESS_TOKEN=abc
-    # $ export HARVEST_ACCOUNT_ID=12345678
-    client = Harvesting::Client.new
-    client.me
-    > => #<Harvesting::Models::User:0x007ff8830658f0 @attributes={"id"=>2108614, "first_name"=>"Ernesto", "last_name"=>"Tagwerker", ... >
+```ruby
+# $ export HARVEST_ACCESS_TOKEN=abc
+# $ export HARVEST_ACCOUNT_ID=12345678
+client = Harvesting::Client.new
+client.me
+# => #<Harvesting::Models::User:0x007ff8830658f0 @attributes={"id"=>2108614, "first_name"=>"Ernesto", "last_name"=>"Tagwerker", ... >
+```
 
 If you don't specify a valid combination of token and account id, your code will
 raise this error:
 
-    client = Harvesting::Client.new(access_token: "foo", account_id: "bar")
-    client.me
-    > Harvesting::AuthenticationError: {"error":"invalid_token","error_description":"The access token provided is expired, revoked, malformed or invalid for other reasons."}
+```ruby
+client = Harvesting::Client.new(access_token: "foo", account_id: "bar")
+client.me
+# Harvesting::AuthenticationError: {"error":"invalid_token","error_description":"The access token provided is expired, revoked, malformed or invalid for other reasons."}
+```
 
 If your personal token and account id are valid, you should see something like
 this:
 
-    client = Harvesting::Client.new(access_token: "<your token here>", account_id: "<your account id here>")
-    user = client.me
-    > => #<Harvesting::Models::User:0x007ff8830658f0 @attributes={"id"=>2108614, "first_name"=>"Ernesto", "last_name"=>"Tagwerker", ... >
+```ruby
+client = Harvesting::Client.new(access_token: "<your token here>", account_id: "<your account id here>")
+user = client.me
+# => #<Harvesting::Models::User:0x007ff8830658f0 @attributes={"id"=>2108614, "first_name"=>"Ernesto", "last_name"=>"Tagwerker", ... >
 
-    user.id
-    > => 2108614
+user.id
+# => 2108614
+```
 
 ### Clients
 
-    client.clients
-    > => [#<Harvesting::Models::Client:0x007ff718d65fd0 @attributes={"id"=>6760580, "name"=>"Toto", "is_active"=>true, "address"=>"" ... >
+```ruby
+client.clients
+# => [#<Harvesting::Models::Client:0x007ff718d65fd0 @attributes={"id"=>6760580, "name"=>"Toto", "is_active"=>true, "address"=>"" ... >
 
-    client = client.clients.first
-    > => #<Harvesting::Models::Client:0x007ff718cf5fc8 @attributes={"id"=>6760580, "name"=>"Toto",
-    ... >
+client = client.clients.first
+# => #<Harvesting::Models::Client:0x007ff718cf5fc8 @attributes={"id"=>6760580, "name"=>"Toto",
+# ... >
+```
 
 ### Time Entries
 
-    time_entries = client.time_entries
-    > => #<Harvesting::Models::TimeEntries:0x007ff71913e3a0 @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>14, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/time_entries?limit=1&page=1&per_page=100", "next"=>nil, "previous"=>nil, "last"=>"https://api.harvestapp.com/v2/time_entries?limit=1&page=1&per_page=100"}}, ... >
+```ruby
+time_entries = client.time_entries
+# => #<Harvesting::Models::TimeEntries:0x007ff71913e3a0 @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>14, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/time_entries?limit=1&page=1&per_page=100", "next"=>nil, "previous"=>nil, "last"=>"https://api.harvestapp.com/v2/time_entries?limit=1&page=1&per_page=100"}}, ... >
 
-    entry = time_entries.first
-    > => #<Harvesting::Models::TimeEntry:0x007ff71913dfe0 @attributes={"id"=>792860513, "spent_date"=>"2018-05-14", "hours"=>1.0, "notes"=>"hacked the things", "is_locked"=>false, "locked_reason"=>nil, "is_closed"=>false, "is_billed"=>false, "timer_started_at"=>nil, "started_time"=>nil, "ended_time"=>nil, "is_running"=>false, "billable"=>true, "budgeted"=>false, "billable_rate"=>nil, "cost_rate ... >
+entry = time_entries.first
+# => #<Harvesting::Models::TimeEntry:0x007ff71913dfe0 @attributes={"id"=>792860513, "spent_date"=>"2018-05-14", "hours"=>1.0, "notes"=>"hacked the things", "is_locked"=>false, "locked_reason"=>nil, "is_closed"=>false, "is_billed"=>false, "timer_started_at"=>nil, "started_time"=>nil, "ended_time"=>nil, "is_running"=>false, "billable"=>true, "budgeted"=>false, "billable_rate"=>nil, "cost_rate ... >
+```
 
 ### Tasks
 
-    tasks = client.tasks
-    > => #<Harvesting::Models::Tasks:0x007ff718897990 @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>6, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/tasks?page=1&per_page=100", "next"=>nil, ... >
+```ruby
+tasks = client.tasks
+# => #<Harvesting::Models::Tasks:0x007ff718897990 @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>6, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/tasks?page=1&per_page=100", "next"=>nil, ... >
+```
 
 ### Projects
 
-    projects = client.projects
-    > => #<Harvesting::Models::Projects:0x007ff718e1c8e8 @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>1, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/projects?page=1&per_page=100", ... >
+```ruby
+projects = client.projects
+# => #<Harvesting::Models::Projects:0x007ff718e1c8e8 @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>1, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/projects?page=1&per_page=100", ... >
+
+project = projects.first
+# => #<Harvesting::Models::Project:0x007ff718e1c618 @attributes={"id"=>17367712, "name"=>"Foo", "code"=>"", "is_active"=>true, "is_billable"=>true, "is_fixed_fee"=>false, "bill_by"=>"none", "budget"=>nil, "budget_by"=>"none", "budget_is_monthly"=>false, "notify_when_over_budget"=>false, "over_budget_notification_percentage"=>80.0, "show_budget_to_all"=>false, "created_at"=>"2018-05-13T03:30:06Z", ... >
+```
+
+### Invoices
+```ruby
+invoices = client.invoices
+# => #<Harvesting::Models::Invoices:0x00007fc8905671f0 @models={}, @attributes={"per_page"=>100, "total_pages"=>1, "total_entries"=>3, "next_page"=>nil, "previous_page"=>nil, "page"=>1, "links"=>{"first"=>"https://api.harvestapp.com/v2/invoices?page=1&per_page=100", ... >
+
+invoice = invoices.first
+# => #<Harvesting::Models::Invoice:0x00007f8c37eb6d18 @models={}, @attributes={"id"=>23831208, "client_key"=>"73688e97a43ed497ace45939eb76db6b18427b80", "number"=>"3", "purchase_order"=>"", "amount"=>750.0, "due_amount"=>750.0, "tax"=>nil, "tax_amount"=>0.0, "tax2"=>nil, "tax2_amount"=>0.0, "discount"=>nil, "discount_amount"=>0.0, "subject"=>"", "notes"=>"", "state"=>"draft", "period_start"=>nil, ... >
+```
+
+An invoice can have many line items:
+```ruby
+line_items = invoice.line_items
+# => [#<Harvesting::Models::LineItem:0x00007f92617ce8e0 @models={}, @attributes={"id"=>109677268, "kind"=>"Service", "description"=>"", "quantity"=>3.0, "unit_price"=>250.0, "amount"=>750.0, "taxed"=>false, "taxed2"=>false, "project"=>{"id"=>24566828, "name"=>"Harvest Billing Automation", "code"=>""}}, ... >]
+```
 
-    project = projects.first
-    > => #<Harvesting::Models::Project:0x007ff718e1c618 @attributes={"id"=>17367712, "name"=>"Foo", "code"=>"", "is_active"=>true, "is_billable"=>true, "is_fixed_fee"=>false, "bill_by"=>"none", "budget"=>nil, "budget_by"=>"none", "budget_is_monthly"=>false, "notify_when_over_budget"=>false, "over_budget_notification_percentage"=>80.0, "show_budget_to_all"=>false, "created_at"=>"2018-05-13T03:30:06Z", ... >
+You can filter invoices by various attributes. E.g. `client.invoices(state: "draft")` only returns invoices in a draft state.
 
 ### Nested Attributes
 
 The Harvest v2 API embeds some data in JSON objects. You can access nested attributes quite naturally.
 For example, to access the user id for a time entry instance, `entry`, use:
 
-    entry.user.id
+```ruby
+entry.user.id
+```
 
 Or to access the name of the client on a project instance, `project`:
-
-    project.client.name
+```ruby
+project.client.name
+```
 
 ## Tips
 
@@ -109,7 +146,7 @@ Or to access the name of the client on a project instance, `project`:
 
 When you need to delete all items, care needs to be taken, because the API uses pagination. The following code will only delete data from _every other_ page.
 
-```
+```ruby
 # WARNING - only deletes every other page
 client.time_entries.each do |time_entry|
   time_entry.delete
@@ -120,7 +157,7 @@ While iterating over items from the first page, all of those items will be delet
 
 Instead you need to make sure you get access to all of the time entry objects before you try to delete any of them. The easiest way to do this is to convert the `Enumerable` instance into an `Array`, by calling `#to_a`, before you iterate over it.
 
-```
+```ruby
 # GOOD - This should do what you want
 client.time_entries.to_a.each do |time_entry|
   time_entry.delete

data/RELEASE_NOTES.md

@@ -1,6 +1,24 @@
 # RELEASE NOTES
 
-### Version 0.3.0 - Jan 22, 2018
+### Version 0.4.0 - June 6, 2020
+
+**Notes**
+- Added Ruby 2.5.1 to version matrix in Travis: https://github.com/ombulabs/harvesting/pull/31
+- Associated time entries for project: https://github.com/ombulabs/harvesting/pull/32
+- Add require forwardable in havest_record_collection model: https://github.com/ombulabs/harvesting/pull/40
+- Add syntax highlighting to readme examples: https://github.com/ombulabs/harvesting/pull/41
+- Rename the client key as harvest_client to avoid confusion: https://github.com/ombulabs/harvesting/pull/43
+- Update rake requirement from ~> 10.0 to ~> 13.0: https://github.com/ombulabs/harvesting/pull/44
+- Bump ffi from 1.9.23 to 1.12.2: https://github.com/ombulabs/harvesting/pull/45
+- Ability to supply filter options to the invoice end point and a model for line items on an invoice.: https://github.com/ombulabs/harvesting/pull/46
+
+**Bug Fixes**
+
+- Complete pending test: https://github.com/ombulabs/harvesting/pull/28
+- Fixed Code Climate link: https://github.com/ombulabs/harvesting/pull/38
+
+
+### Version 0.3.0 - Jan 22, 2019
 
 **Notes**
 

data/harvesting.gemspec

@@ -6,8 +6,8 @@ require "harvesting/version"
 Gem::Specification.new do |spec|
   spec.name          = "harvesting"
   spec.version       = Harvesting::VERSION
-  spec.authors       = ["Ernesto Tagwerker"]
-  spec.email         = ["ernesto+github@ombulabs.com"]
+  spec.authors       = ["Ernesto Tagwerker", "M. Scott Ford"]
+  spec.email         = ["ernesto+github@ombulabs.com", "scott@mscottford.com"]
 
   spec.summary       = %q{Ruby wrapper for the Harvest API v2.0}
   spec.description   = %q{Interact with the Harvest API v2.0 from your Ruby application}
@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "http", "~> 3.3", ">= 3.3"
 
   spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "guard-rspec", "~> 4.7", ">= 4.7"
   spec.add_development_dependency "byebug", "~> 10.0", ">= 10.0"

data/lib/harvesting.rb

@@ -9,9 +9,11 @@ require "harvesting/models/harvest_record_collection"
 require "harvesting/models/client"
 require "harvesting/models/user"
 require "harvesting/models/project"
-require "harvesting/models/invoice"
 require "harvesting/models/task"
-require "harvesting/models/task_assignment"
+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/tasks"
@@ -19,6 +21,9 @@ 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"
 

data/lib/harvesting/client.rb

@@ -3,12 +3,20 @@ 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
 
-    # @param opts
+    # Returns a new instance of `Client`
+    #
+    #     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
@@ -18,45 +26,68 @@ 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
 
+    # @return [Array<Harvesting::Models::Client>]
     def clients
       get("clients")["clients"].map do |result|
-        Harvesting::Models::Client.new(result, client: self)
+        Harvesting::Models::Client.new(result, harvest_client: self)
       end
     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), 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), 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), 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, client: self)
+      Harvesting::Models::Users.new(get("users", opts), opts, harvest_client: self)
     end
 
-    def invoices
-      get("invoices")["invoices"].map do |result|
-        Harvesting::Models::Invoice.new(result, 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)
@@ -65,6 +96,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)
@@ -73,13 +108,24 @@ module Harvesting
       entity
     end
 
+    # 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(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?

data/lib/harvesting/enumerable.rb

@@ -1,3 +1,6 @@
+# `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

data/lib/harvesting/models/base.rb

@@ -1,54 +1,62 @@
 module Harvesting
   module Models
     class Base
+      # @return [Hash]
       attr_accessor :attributes
+      # @return [Harvesting::Model::Client]
       attr_reader :harvest_client
 
       def initialize(attrs, opts = {})
         @models = {}
         @attributes = attrs.dup
-        @harvest_client = opts[:client] || Harvesting::Client.new(opts)
-      end
-
-      def self.attributed(*attribute_names)
-        attribute_names.each do |attribute_name|
-          define_method(attribute_name) do
-            @attributes[__method__.to_s]
-          end
-        end
-      end
-
-      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] || {}, client: harvest_client)
-          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
         @harvest_client.create(self)
       end
 
+      # It updates the record.
+      #
+      # @see Client#update
+      # @return [Harvesting::Models::Base]
       def update
         @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), client: @harvest_client)
+        self.class.new(@harvest_client.get(path), harvest_client: @harvest_client)
       end
 
       # Retrieves an instance of the object by ID
@@ -57,9 +65,54 @@ module Harvesting
       # @param opts [Hash] options to pass along to the `Harvesting::Client`
       #   instance
       def self.get(id, opts = {})
-        client = opts[:client] || Harvesting::Client.new(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,5 +1,8 @@
 module Harvesting
   module Models
+    # 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,

data/lib/harvesting/models/contact.rb

@@ -1,5 +1,8 @@
 module Harvesting
   module Models
+    # 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,
@@ -17,7 +20,7 @@ module Harvesting
       def path
         @attributes['id'].nil? ? "contacts" : "contacts/#{@attributes['id']}"
       end
-
+      
       def to_hash
         { client_id: client.id }.merge(super)
       end

data/lib/harvesting/models/harvest_record_collection.rb

@@ -1,3 +1,5 @@
+require 'forwardable'
+
 module Harvesting
   module Models
     class HarvestRecordCollection < Base

data/lib/harvesting/models/invoice.rb

@@ -1,9 +1,11 @@
 module Harvesting
   module Models
+    # An invoice record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/invoices-api/invoices/invoices/
     class Invoice < HarvestRecord
       attributed :id,
                  :client_key,
-                 :line_items,
                  :number,
                  :purchase_order,
                  :amount,
@@ -29,6 +31,11 @@ module Harvesting
                  :closed_at,
                  :created_at,
                  :updated_at
+
+      def line_items
+        @line_items ||= @attributes['line_items'].map { |line_item_attributes| LineItem.new line_item_attributes, { harvest_client: harvest_client } }
+      end
+
       def path
         @attributes['id'].nil? ? "invoices" : "invoices/#{@attributes['id']}"
       end

data/lib/harvesting/models/invoices.rb

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

data/lib/harvesting/models/line_item.rb

@@ -0,0 +1,19 @@
+module Harvesting
+  module Models
+    # A line item on an invoice from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/invoices-api/invoices/invoices/
+    class LineItem < HarvestRecord
+      attributed :id,
+                 :kind,
+                 :description,
+                 :quantity,
+                 :unit_price,
+                 :amount,
+                 :taxed,
+                 :taxed2
+
+      modeled project: Project
+    end
+  end
+end

data/lib/harvesting/models/project.rb

@@ -1,5 +1,8 @@
 module Harvesting
   module Models
+    # A project record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/projects-api/projects/projects/
     class Project < HarvestRecord
       attributed :id,
                  :name,
@@ -30,10 +33,26 @@ module Harvesting
       def path
         @attributes['id'].nil? ? "projects" : "projects/#{@attributes['id']}"
       end
-
+      
       def to_hash
         { client_id: client.id }.merge(super)
       end
+
+      def time_entries
+        harvest_client.time_entries(project_id: self.id)
+      end
+
+      # Provides access to the user assignments that are associated with this
+      # project.
+      def user_assignments
+        harvest_client.user_assignments(project_id: self.id)
+      end
+
+      # Provides access to the task assignments that are associated with this
+      # project.
+      def task_assignments
+        harvest_client.task_assignments(project_id: self.id)
+      end
     end
   end
 end

data/lib/harvesting/models/{task_assignment.rb → project_task_assignment.rb}

@@ -1,6 +1,9 @@
 module Harvesting
   module Models
-    class TaskAssignment < HarvestRecord
+    # A task assignment record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/projects-api/projects/task-assignments/
+    class ProjectTaskAssignment < HarvestRecord
       attributed :id,
                  :is_active,
                  :billable,
@@ -21,11 +24,10 @@ module Harvesting
       #   # TODO: handle case where project's id is part of json object
       #   @attributes["project_id"]
       # end
-
+      
       def to_hash
         { project_id: project.id, task_id: task.id }.merge(super)
       end
-
     end
   end
 end

data/lib/harvesting/models/project_task_assignments.rb

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

data/lib/harvesting/models/project_user_assignment.rb

@@ -0,0 +1,25 @@
+module Harvesting
+  module Models
+    class ProjectUserAssignment < HarvestRecord
+      attributed :id,
+                 :is_active,
+                 :is_project_manager,
+                 :hourly_rate,
+                 :budget,
+                 :created_at,
+                 :updated_at
+
+      modeled project: Project,
+              user: User
+
+      def path
+        base_url = "projects/#{project.id}/user_assignments"
+        @attributes['id'].nil? ? base_url : "#{base_url}/#{@attributes['id']}"
+      end
+
+      def to_hash
+        { project_id: project.id, user_id: user.id }.merge(super)
+      end
+    end
+  end
+end

data/lib/harvesting/models/project_user_assignments.rb

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

data/lib/harvesting/models/projects.rb

@@ -5,7 +5,7 @@ module Harvesting
       def initialize(attrs, query_opts = {}, opts = {})
         super(attrs.reject {|k,v| k == "projects" }, query_opts, opts)
         @entries = attrs["projects"].map do |entry|
-          Project.new(entry, client: opts[:client])
+          Project.new(entry, harvest_client: opts[:harvest_client])
         end
       end
 

data/lib/harvesting/models/task.rb

@@ -1,9 +1,12 @@
 module Harvesting
   module Models
+    # A task record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/tasks-api/tasks/tasks/
     class Task < HarvestRecord
       attributed :id,
                  :name,
-                 :billable_by_default, 
+                 :billable_by_default,
                  :default_hourly_rate,
                  :is_default,
                  :is_active,

data/lib/harvesting/models/tasks.rb

@@ -5,7 +5,7 @@ module Harvesting
       def initialize(attrs, query_opts = {}, opts = {})
         super(attrs.reject {|k,v| k == "tasks" }, query_opts, opts)
         @entries = attrs["tasks"].map do |entry|
-          Task.new(entry, client: opts[:client])
+          Task.new(entry, harvest_client: opts[:harvest_client])
         end
       end
 

data/lib/harvesting/models/time_entries.rb

@@ -5,7 +5,7 @@ module Harvesting
       def initialize(attrs, query_opts = {}, opts = {})
         super(attrs.reject {|k,v| k == "time_entries" }, query_opts, opts)
         @entries = attrs["time_entries"].map do |entry|
-          TimeEntry.new(entry, client: opts[:client])
+          TimeEntry.new(entry, harvest_client: opts[:harvest_client])
         end
       end
 

data/lib/harvesting/models/time_entry.rb

@@ -1,5 +1,8 @@
 module Harvesting
   module Models
+    # A time entry record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/
     class TimeEntry < HarvestRecord
       attributed :id,
                  :spent_date,
@@ -20,14 +23,14 @@ module Harvesting
                  :invoice,
                  :external_reference,
                  :created_at,
-                 :updated_at,
-                 :user_assignment # temporarily return the hash itself until the model is added
+                 :updated_at
 
       modeled project: Project,
               user: User,
               task: Task,
               client: Client,
-              task_assignment: TaskAssignment
+              task_assignment: ProjectTaskAssignment,
+              user_assignment: ProjectUserAssignment
 
 
       def path

data/lib/harvesting/models/user.rb

@@ -1,7 +1,11 @@
 module Harvesting
   module Models
+    # An user record from your Harvest account.
+    #
+    # For more information: https://help.getharvest.com/api-v2/users-api/users/users/
     class User < HarvestRecord
       attributed :id,
+                 :name,
                  :first_name,
                  :last_name,
                  :email,
@@ -26,6 +30,10 @@ module Harvesting
       def path
         @attributes['id'].nil? ? "users" : "users/#{@attributes['id']}"
       end
+
+      def name
+        @attributes['name'].nil? ? "#{first_name} #{last_name}" : @attributes['name']
+      end
     end
   end
 end

data/lib/harvesting/models/users.rb

@@ -5,7 +5,7 @@ module Harvesting
       def initialize(attrs, query_opts = {}, opts = {})
         super(attrs.reject {|k,v| k == "users" }, query_opts, opts)
         @entries = attrs["users"].map do |entry|
-          User.new(entry, client: opts[:client])
+          User.new(entry, harvest_client: opts[:harvest_client])
         end
       end
 

data/lib/harvesting/version.rb

@@ -1,3 +1,3 @@
 module Harvesting
-  VERSION = "0.3.0".freeze
+  VERSION = "0.4.0".freeze
 end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: harvesting
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ernesto Tagwerker
+- M. Scott Ford
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-22 00:00:00.000000000 Z
+date: 2020-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -50,14 +51,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -175,6 +176,7 @@ dependencies:
 description: Interact with the Harvest API v2.0 from your Ruby application
 email:
 - ernesto+github@ombulabs.com
+- scott@mscottford.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -206,10 +208,15 @@ files:
 - lib/harvesting/models/harvest_record.rb
 - lib/harvesting/models/harvest_record_collection.rb
 - lib/harvesting/models/invoice.rb
+- lib/harvesting/models/invoices.rb
+- lib/harvesting/models/line_item.rb
 - lib/harvesting/models/project.rb
+- lib/harvesting/models/project_task_assignment.rb
+- lib/harvesting/models/project_task_assignments.rb
+- lib/harvesting/models/project_user_assignment.rb
+- lib/harvesting/models/project_user_assignments.rb
 - lib/harvesting/models/projects.rb
 - lib/harvesting/models/task.rb
-- lib/harvesting/models/task_assignment.rb
 - lib/harvesting/models/tasks.rb
 - lib/harvesting/models/time_entries.rb
 - lib/harvesting/models/time_entry.rb
@@ -235,8 +242,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.8
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Ruby wrapper for the Harvest API v2.0