@@ -1,146 +1,173 @@ -= harvest - -A ruby library wrapping (most of) the Harvest Api. - -== DESCRIPTION: - -This library uses ActiveResource and activeresource_throttle to provide simple, reliable access to the Harvest Api. Good for building reporting scripts and simple apps. - -Note that this library does not support the complete Harvest Api at this time. See Features/Issues below for details. - -== USAGE: - -=== Creating a new harvest object: - -All calls to the Harvest API will originate from a Harvest object. Initialize it like so: - - @harvest = Harvest(:email => "joe@example.com", - :password => "secret", - :sub_domain => "joeandcompany", - :headers => {"User-Agent" => "MyCompany"}) - -The _headers_ argument is optional. Use <b>:ssl => true</b> if your account requires HTTPS. - -=== Clients - -Index - @harvest.clients.find(:all) -Show - @harvest.clients.find(43235) -Create - @client = @harvest.clients.new - @client.attributes = {:name => "Company, LLC", :details => "New York, NY"} - @client.save -Update - @client.first_name = "Smith" - @client.save -Destroy - @client.destroy - -Toggle (Active/Inactive) - @client.toggle - -=== Tasks - -Index - @harvest.tasks.find(:all) -Show - @harvest.tasks.find(123) -Create - @task = @harvest.tasks.new - @task.attributes = {:name => "Meeting", :billable_by_default => false, - :is_default => false, :default_hourly_rate => 100} - @task.save -Update - @task.name = "Client Meeting" - @task.save -Destroy - @task.destroy - -=== People - -Index - @harvest.people.find(:all) -Show - @harvest.people.find(123) - -=== Projects - -Index - @harvest.projects.find(:all) -Show - @harvest.projects.find(123) -Create - @project = @harvest.projects.new - @project.attributes = {:name => "Refactor", :active => true, - :bill_by => "None", :client_id => @client.id, } - @project.save -Update - @project.name = "Mega-Refactor" - @project.save -Destroy - @project.destroy - -Toggle (Active/Inactive) - @project.toggle - -==== User and Task Assignments - - @project.users.find(:all) - @project.users.find(:first) - - @project.tasks.find(:all) - @project.tasks.find(:first) - -=== Reports - - @project.entries(:from => Time.now, :to => Time.now) - @project.entries(:from => Time.now, :to => Time.now, :user_id => @person.id) - - @person.entries(:from => Time.now, :to => Time.now) - @person.expenses(:from => Time.now, :to => Time.now) - -== FEATURES/PROBLEMS: - -Supports most of the Harvest Api (http://www.getharvest.com/api). - -Though RESTful, the Harvest Api does not entirely follow ActiveResource conventions. In order to support the complete API, certain customizations will be required. <b>We welcome any contributions/modifications to help complete this Api.</b> - -The following Api features are incomplete due to incompatibilities with ActiveResource conventions (CRUD actions in parentheses): - -1. People (CUD) -2. User & Task Assignments (CUD) -3. Expenses (CUD) - -In addition, the following have not been implemented at all due to time constraints: - -1. Time Tracking Api -2. Invoices, Invoice Payments, Invoice Categories, and Invoice Messages - -Expect a more complete library in the near future. Again, contributions are welcome. - -== TEST SUITE - -This library includes a fairly thorough set of unit and integration tests. The unit tests can be run with the "rake" command. - -The integration tests require a Harvest account. It is best to use a trial account when running these tests. - -The credentials may be entered in test/test_helper.rb. To run the integration suite: - - rake test:integration - -Note that the integration test structure is somewhat unorthodox, as it requires tests to run in a particular order. The main test file is test/integration/harvest_integration_test.rb. Examine this to see how the integration suite works. - -== REQUIREMENTS: - -Requires active_resource >= 2.1 and activeresource_throttle >= 1.0. - -active_resource_throttle should install automaticallt, but just in case you need to install manually: - - gem sources -a http://gems.github.com - sudo gem install aiaio-active_resource_throttle - -== INSTALL: - - gem sources -a http://gems.github.com - gem install aiaio-harvest += harvest + +A ruby library wrapping (most of) the Harvest Api. + +== DESCRIPTION: + +This library uses ActiveResource and activeresource_throttle to provide simple, reliable access to the Harvest Api. Good for building reporting scripts and simple apps. + +Note that this library does not support the complete Harvest Api at this time. See Features/Issues below for details. + +== USAGE: + +=== Creating a new harvest object: + +All calls to the Harvest API will originate from a Harvest object. Initialize it like so: + + @harvest = Harvest(:email => "joe@example.com", + :password => "secret", + :sub_domain => "joeandcompany", + :headers => {"User-Agent" => "MyCompany"}) + +The _headers_ argument is optional. Use <b>:ssl => true</b> if your account requires HTTPS. + +=== Clients + +Index + @harvest.clients.find(:all) +Show + @harvest.clients.find(43235) +Create + @client = @harvest.clients.new + @client.attributes = {:name => "Company, LLC", :details => "New York, NY"} + @client.save +Update + @client.first_name = "Smith" + @client.save +Destroy + @client.destroy + +Toggle (Active/Inactive) + @client.toggle + +=== Tasks + +Index + @harvest.tasks.find(:all) +Show + @harvest.tasks.find(123) +Create + @task = @harvest.tasks.new + @task.attributes = {:name => "Meeting", :billable_by_default => false, + :is_default => false, :default_hourly_rate => 100} + @task.save +Update + @task.name = "Client Meeting" + @task.save +Destroy + @task.destroy + +=== People + +Index + @harvest.people.find(:all) +Show + @harvest.people.find(123) + +=== Projects + +Index + @harvest.projects.find(:all) +Show + @harvest.projects.find(123) +Create + @project = @harvest.projects.new + @project.attributes = {:name => "Refactor", :active => true, + :bill_by => "None", :client_id => @client.id, } + @project.save +Update + @project.name = "Mega-Refactor" + @project.save +Destroy + @project.destroy + +Toggle (Active/Inactive) + @project.toggle + +=== Invoices + +Index + @invoices = @harvest.invoices.find(:all) + +Show + @invoice = @harvest.invoices.find(1) + +Find By Invoice Number + @invoice = @harvest.invoices.find_by_number('200') + +Create + @invoice = @harvest.invoices.new + @invoice.attributes = {:amount => '250.32', :client_id => @client.id} + @invoice.save + +Update + @invoice.notes = "Pending payment" + @invoice.save + +Destroy + @invoice.destroy + +Return parsed csv line items + @invoice.parsed_csv_line_items + +==== User and Task Assignments + + @project.users.find(:all) + @project.users.find(:first) + + @project.tasks.find(:all) + @project.tasks.find(:first) + +=== Reports + + @project.entries(:from => Time.now, :to => Time.now) + @project.entries(:from => Time.now, :to => Time.now, :user_id => @person.id) + + @person.entries(:from => Time.now, :to => Time.now) + @person.expenses(:from => Time.now, :to => Time.now) + + +== FEATURES/PROBLEMS: + +Supports most of the Harvest Api (http://www.getharvest.com/api). + +Though RESTful, the Harvest Api does not entirely follow ActiveResource conventions. In order to support the complete API, certain customizations will be required. <b>We welcome any contributions/modifications to help complete this Api.</b> + +The following Api features are incomplete due to incompatibilities with ActiveResource conventions (CRUD actions in parentheses): + +1. People (CUD) +2. User & Task Assignments (CUD) +3. Expenses (CUD) + +In addition, the following have not been implemented at all due to time constraints: + +1. Time Tracking Api +2. Invoices, Invoice Payments, Invoice Categories, and Invoice Messages + +Expect a more complete library in the near future. Again, contributions are welcome. + +== TEST SUITE + +This library includes a fairly thorough set of unit and integration tests. The unit tests can be run with the "rake" command. + +The integration tests require a Harvest account. It is best to use a trial account when running these tests. + +The credentials may be entered in test/test_helper.rb. To run the integration suite: + + rake test:integration + +Note that the integration test structure is somewhat unorthodox, as it requires tests to run in a particular order. The main test file is test/integration/harvest_integration_test.rb. Examine this to see how the integration suite works. + +== REQUIREMENTS: + +Requires active_resource >= 2.1 and activeresource_throttle >= 1.0. + +active_resource_throttle should install automaticallt, but just in case you need to install manually: + + gem sources -a http://gems.github.com + sudo gem install aiaio-active_resource_throttle + +== INSTALL: + + gem sources -a http://gems.github.com + gem install aiaio-harvest README.rdoc @@ -2,7 +2,7 @@ Gem::Specification.new do |s| s.name = "harvest" - s.version = "0.8.1" + s.version = "0.8.2" s.authors = ["Kyle Banker", "Alexander Interactive, Inc."] s.date = "2008-12-17" s.summary = "A wrapper for the Harvest Api. See http://getharvest.com/api for details." harvest.gemspec @@ -36,16 +36,16 @@ class InvoiceTest < Test::Unit::TestCase end should "create a new invoice" do - project = Harvest::Resources::Invoice.new(:number => "200") - project.save + invoice = Harvest::Resources::Invoice.new(:number => "200") + invoice.save expected_request = ActiveResource::Request.new(:post, "/invoices.xml") assert ActiveResource::HttpMock.requests.include?(expected_request) end should "update an existing invoice" do - project = Harvest::Resources::Invoice.find(1) - project.number = "200" - project.save + invoice = Harvest::Resources::Invoice.find(1) + invoice.number = "200" + invoice.save expected_request = ActiveResource::Request.new(:put, "/invoices/1.xml") assert ActiveResource::HttpMock.requests.include?(expected_request) end test/unit/resources/invoice_test.rb @@ -1,151 +1,150 @@ -require File.join(File.dirname(__FILE__), "..", "..", "test_helper") - -class PersonTest < Test::Unit::TestCase - - def setup_resources - @person_xml = {:id => 1, :name => "Joe Coder"}.to_xml(:root => "person") - @people = [{:id => 1, :name => "Joe Coder"}].to_xml(:root => "people") - @entry = [{:id => 2, :project_id => 50}].to_xml(:root => "day-entries") - @entries = [{:id => 1, :project_id => "25"}, - {:id => 2, :project_id => 50} ].to_xml(:root => "day-entries") - @expenses = [{:id => 1, :project_id => "25"}, - {:id => 2, :project_id => 50} ].to_xml(:root => "expenses") - end - - def mock_responses - ActiveResource::HttpMock.respond_to do |mock| - mock.get "/people.xml", {}, @people - mock.get "/people/1.xml", {}, @person_xml - mock.post "/people.xml", {}, @person_xml, 201, "Location" => "/people/5.xml" - mock.put "/people/1.xml", {}, nil, 200 - mock.delete "/people/1.xml", {}, nil, 200 - mock.put "/people/1/toggle.xml", {}, nil, 200 - mock.get "/people/1/entries.xml?from=20080101&to=20080131", {}, @entries - mock.get "/people/1/entries.xml?from=20080101&project_id=3&to=20080131", {}, @entry - mock.get "/people/1/expenses.xml?from=20080101&to=20080131", {}, @expenses - end - end - - context "People CRUD actions -- " do - setup do - setup_resources - mock_responses - end - - should "get index" do - Harvest::Resources::Person.find(:all) - expected_request = ActiveResource::Request.new(:get, "/people.xml") - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "get a single project" do - Harvest::Resources::Person.find(1) - expected_request = ActiveResource::Request.new(:get, "/people/1.xml") - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "create a new project" do - project = Harvest::Resources::Person.new(:name => "Widgets&Co") - project.save - expected_request = ActiveResource::Request.new(:post, "/people.xml") - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "update an existing project" do - project = Harvest::Resources::Person.find(1) - project.name = "Joe Coder" - project.save - expected_request = ActiveResource::Request.new(:put, "/people/1.xml") - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "delete an existing project" do - Harvest::Resources::Person.delete(1) - expected_request = ActiveResource::Request.new(:delete, "/people/1.xml") - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - end - - - context "Toggling active/inactive status" do - setup do - setup_resources - mock_responses - end - - should "hit the toggle method" do - person = Harvest::Resources::Person.find(1) - person.toggle - expected_request = ActiveResource::Request.new(:put, "/people/1/toggle.xml") - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "return 200 Success toggle method" do - person = Harvest::Resources::Person.find(1) - assert person.toggle.code == 200 - end - - end - - context "Getting entries" do - setup do - setup_resources - mock_responses - @person = Harvest::Resources::Person.find(1) - end - - should "raise an error if start and end are not included" do - assert_raises ArgumentError, "Must specify :start and :end as dates." do - @person.entries - end - end - - should "raise an error if end date precedes start date" do - assert_raises ArgumentError, "Must specify :start and :end as dates." do - @person.entries(:from => Time.utc(2007, 1, 1), :to => Time.utc(2006, 1, 1)) - end - end - - should "return the project site prefix" do - entry_class = Harvest::Resources::Entry.clone - entry_class.person_id = @person.id - assert_equal "http://example.com/people/1", entry_class.site.to_s - end - - end - - context "Reports -- " do - setup do - setup_resources - mock_responses - @from = Time.utc(2008, 1, 1) - @to = Time.utc(2008, 1, 31) - @person = Harvest::Resources::Person.find(1) - @request_path = "/people/1/entries.xml?from=20080101&to=20080131" - @expense_path = "/people/1/expenses.xml?from=20080101&to=20080131" - end - - should "get all entries for a given date range" do - @person.entries(:from => @from, :to => @to) - expected_request = ActiveResource::Request.new(:get, @request_path) - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "get all entries for the given date range and user" do - path = "/people/1/entries.xml?from=20080101&project_id=3&to=20080131" - @person.entries(:from => @from, :to => @to, :project_id => 3) - expected_request = ActiveResource::Request.new(:get, path) - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - should "return all expense entries logged by the given user" do - @person.expenses(:from => @from, :to => @to) - expected_request = ActiveResource::Request.new(:get, @expense_path) - p ActiveResource::HttpMock.requests - assert ActiveResource::HttpMock.requests.include?(expected_request) - end - - end - -end \ No newline at end of file +require File.join(File.dirname(__FILE__), "..", "..", "test_helper") + +class PersonTest < Test::Unit::TestCase + + def setup_resources + @person_xml = {:id => 1, :name => "Joe Coder"}.to_xml(:root => "person") + @people = [{:id => 1, :name => "Joe Coder"}].to_xml(:root => "people") + @entry = [{:id => 2, :project_id => 50}].to_xml(:root => "day-entries") + @entries = [{:id => 1, :project_id => "25"}, + {:id => 2, :project_id => 50} ].to_xml(:root => "day-entries") + @expenses = [{:id => 1, :project_id => "25"}, + {:id => 2, :project_id => 50} ].to_xml(:root => "expenses") + end + + def mock_responses + ActiveResource::HttpMock.respond_to do |mock| + mock.get "/people.xml", {}, @people + mock.get "/people/1.xml", {}, @person_xml + mock.post "/people.xml", {}, @person_xml, 201, "Location" => "/people/5.xml" + mock.put "/people/1.xml", {}, nil, 200 + mock.delete "/people/1.xml", {}, nil, 200 + mock.put "/people/1/toggle.xml", {}, nil, 200 + mock.get "/people/1/entries.xml?from=20080101&to=20080131", {}, @entries + mock.get "/people/1/entries.xml?from=20080101&project_id=3&to=20080131", {}, @entry + mock.get "/people/1/expenses.xml?from=20080101&to=20080131", {}, @expenses + end + end + + context "People CRUD actions -- " do + setup do + setup_resources + mock_responses + end + + should "get index" do + Harvest::Resources::Person.find(:all) + expected_request = ActiveResource::Request.new(:get, "/people.xml") + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "get a single project" do + Harvest::Resources::Person.find(1) + expected_request = ActiveResource::Request.new(:get, "/people/1.xml") + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "create a new project" do + project = Harvest::Resources::Person.new(:name => "Widgets&Co") + project.save + expected_request = ActiveResource::Request.new(:post, "/people.xml") + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "update an existing project" do + project = Harvest::Resources::Person.find(1) + project.name = "Joe Coder" + project.save + expected_request = ActiveResource::Request.new(:put, "/people/1.xml") + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "delete an existing project" do + Harvest::Resources::Person.delete(1) + expected_request = ActiveResource::Request.new(:delete, "/people/1.xml") + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + end + + + context "Toggling active/inactive status" do + setup do + setup_resources + mock_responses + end + + should "hit the toggle method" do + person = Harvest::Resources::Person.find(1) + person.toggle + expected_request = ActiveResource::Request.new(:put, "/people/1/toggle.xml") + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "return 200 Success toggle method" do + person = Harvest::Resources::Person.find(1) + assert person.toggle.code == 200 + end + + end + + context "Getting entries" do + setup do + setup_resources + mock_responses + @person = Harvest::Resources::Person.find(1) + end + + should "raise an error if start and end are not included" do + assert_raises ArgumentError, "Must specify :start and :end as dates." do + @person.entries + end + end + + should "raise an error if end date precedes start date" do + assert_raises ArgumentError, "Must specify :start and :end as dates." do + @person.entries(:from => Time.utc(2007, 1, 1), :to => Time.utc(2006, 1, 1)) + end + end + + should "return the project site prefix" do + entry_class = Harvest::Resources::Entry.clone + entry_class.person_id = @person.id + assert_equal "http://example.com/people/1", entry_class.site.to_s + end + + end + + context "Reports -- " do + setup do + setup_resources + mock_responses + @from = Time.utc(2008, 1, 1) + @to = Time.utc(2008, 1, 31) + @person = Harvest::Resources::Person.find(1) + @request_path = "/people/1/entries.xml?from=20080101&to=20080131" + @expense_path = "/people/1/expenses.xml?from=20080101&to=20080131" + end + + should "get all entries for a given date range" do + @person.entries(:from => @from, :to => @to) + expected_request = ActiveResource::Request.new(:get, @request_path) + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "get all entries for the given date range and user" do + path = "/people/1/entries.xml?from=20080101&project_id=3&to=20080131" + @person.entries(:from => @from, :to => @to, :project_id => 3) + expected_request = ActiveResource::Request.new(:get, path) + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + should "return all expense entries logged by the given user" do + @person.expenses(:from => @from, :to => @to) + expected_request = ActiveResource::Request.new(:get, @expense_path) + assert ActiveResource::HttpMock.requests.include?(expected_request) + end + + end + +end test/unit/resources/person_test.rb ab5fe9ce3b3fbb92f797f39752fd88b59ac342d1 aiaio knb@alexanderinteractive.com http://github.com/aiaio/harvest/commit/485940b1205549c8bea1e0a9c5175c2a51ad7282 485940b1205549c8bea1e0a9c5175c2a51ad7282 2009-06-08T10:11:54-07:00 2009-06-08T10:11:54-07:00 Fixes for invoice support. 51f135a3067b9efeec795ac490f0e8f086e9b7fd aiaio knb@alexanderinteractive.com