harvested 0.3.0 → 0.3.1

data/.document

@@ -0,0 +1,3 @@
+README.md
+lib/**/*.rb
+MIT-LICENSE

data/.gitignore

@@ -18,6 +18,8 @@ coverage
 rdoc
 pkg
 spec.opts
+doc
+.yardoc
 
 ## PROJECT::SPECIFIC
 features/support/harvest_credentials.yml

data/README.md

@@ -8,14 +8,14 @@ This is a Ruby wrapper for the [Harvest API](http://www.getharvest.com/).
 
 ## Examples
 
-    harvest = Harvest.client('yoursubdomain', 'yourusername', 'yourpassword', :ssl => false) # you can enable SSL if your account supports it
+    harvest = Harvest.client('yoursubdomain', 'yourusername', 'yourpassword')
     harvest.projects() # list out projects
     
     client = Harvest::Client.new(:name => "Billable Company LTD.")
     client = harvest.clients.create(client)
     harvest.clients.find(client.id) # returns a Harvest::Client
 
-You can find more examples in `/examples`
+You can find more examples in `/examples` and in the documentation for Harvest::Base
 
 ## Hardy Client
 
@@ -23,11 +23,12 @@ The guys at Harvest built a great API, but there are always dangers in writing c
 
 Using `Harvested#client` your code needs to handle all these situations. However you can also use `Harvested#hardy_client` which will retry errors and wait for Rate Limit resets.
 
-    harvest = Harvest.hardy_client('yoursubdomain', 'yourusername', 'yourpassword', :ssl => false)
+    harvest = Harvest.hardy_client('yoursubdomain', 'yourusername', 'yourpassword')
     harvest.projects() # This will wait for the Rate Limit reset if you have gone over your limit
 
 ## Links
 
+* [Harvested Documentation](http://rdoc.info/projects/zmoazeni/harvested)
 * [Harvest API Documentation](http://www.getharvest.com/api)
 * [Source Code for Harvested](http://github.com/zmoazeni/harvested)
 * [Pivotal Tracker for Harvested](http://www.pivotaltracker.com/projects/63260)

data/Rakefile

@@ -6,7 +6,7 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "harvested"
     gem.summary = %Q{A Ruby Wrapper for the Harvest API http://www.getharvest.com/}
-    gem.description = %Q{Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found at http://www.getharvest.com/api}
+    gem.description = %Q{Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found on their website (http://www.getharvest.com/api). For support hit up the Mailing List (http://groups.google.com/group/harvested)}
     gem.email = "zach.moazeni@gmail.com"
     gem.homepage = "http://github.com/zmoazeni/harvested"
     gem.authors = ["Zach Moazeni"]
@@ -50,3 +50,12 @@ rescue LoadError
 end
 
 task :default => %w(spec features)
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

data/examples/basics.rb

@@ -4,7 +4,7 @@ subdomain = 'yoursubdomain'
 username = 'yourusername'
 password = 'yourpassword'
 
-harvest = Harvest.hardy_client(subdomain, username, password, :ssl => false)
+harvest = Harvest.hardy_client(subdomain, username, password)
 
 # Print out all users, clients, and projects on the account
 puts "Users:"

data/examples/clear_account.rb

@@ -6,7 +6,7 @@
 # username = 'yourusername'
 # password = 'yourpassword'
 # 
-# api = Harvest.hardy_client(subdomain, username, password, :ssl => false)
+# api = Harvest.hardy_client(subdomain, username, password)
 # 
 # raise "Are you sure you want to do this? (comment out this exception if so)"
 # 

data/examples/task_assignments.rb

@@ -4,7 +4,7 @@ subdomain = 'yoursubdomain'
 username = 'yourusername'
 password = 'yourpassword'
 
-harvest = Harvest.hardy_client(subdomain, username, password, :ssl => false)
+harvest = Harvest.hardy_client(subdomain, username, password)
 
 # Create a Client add a Project to that Client
 

data/examples/user_assignments.rb

@@ -4,7 +4,7 @@ subdomain = 'yoursubdomain'
 username = 'userusername'
 password = 'yourpassword'
 
-harvest = Harvest.hardy_client(subdomain, username, password, :ssl => false)
+harvest = Harvest.hardy_client(subdomain, username, password)
 
 # Create a Client, Project, and a User then assign that User to that Project
 

data/harvested.gemspec

@@ -0,0 +1,159 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{harvested}
+  s.version = "0.3.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Zach Moazeni"]
+  s.date = %q{2010-10-14}
+  s.description = %q{Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found on their website (http://www.getharvest.com/api). For support hit up the Mailing List (http://groups.google.com/group/harvested)}
+  s.email = %q{zach.moazeni@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "HISTORY",
+     "MIT-LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "examples/basics.rb",
+     "examples/clear_account.rb",
+     "examples/task_assignments.rb",
+     "examples/user_assignments.rb",
+     "features/account.feature",
+     "features/client_contacts.feature",
+     "features/clients.feature",
+     "features/errors.feature",
+     "features/expense_categories.feature",
+     "features/expenses.feature",
+     "features/hardy_client.feature",
+     "features/projects.feature",
+     "features/reporting.feature",
+     "features/step_definitions/account_steps.rb",
+     "features/step_definitions/assignment_steps.rb",
+     "features/step_definitions/contact_steps.rb",
+     "features/step_definitions/debug_steps.rb",
+     "features/step_definitions/error_steps.rb",
+     "features/step_definitions/expenses_steps.rb",
+     "features/step_definitions/harvest_steps.rb",
+     "features/step_definitions/model_steps.rb",
+     "features/step_definitions/people_steps.rb",
+     "features/step_definitions/report_steps.rb",
+     "features/step_definitions/time_entry_steps.rb",
+     "features/support/env.rb",
+     "features/support/error_helpers.rb",
+     "features/support/fixtures/empty_clients.xml",
+     "features/support/fixtures/over_limit.xml",
+     "features/support/fixtures/receipt.png",
+     "features/support/fixtures/under_limit.xml",
+     "features/support/harvest_credentials.example.yml",
+     "features/support/harvest_helpers.rb",
+     "features/support/inflections.rb",
+     "features/task_assignment.feature",
+     "features/tasks.feature",
+     "features/time_tracking.feature",
+     "features/user_assignments.feature",
+     "features/users.feature",
+     "harvested.gemspec",
+     "lib/harvest/api/account.rb",
+     "lib/harvest/api/base.rb",
+     "lib/harvest/api/clients.rb",
+     "lib/harvest/api/contacts.rb",
+     "lib/harvest/api/expense_categories.rb",
+     "lib/harvest/api/expenses.rb",
+     "lib/harvest/api/projects.rb",
+     "lib/harvest/api/reports.rb",
+     "lib/harvest/api/task_assignments.rb",
+     "lib/harvest/api/tasks.rb",
+     "lib/harvest/api/time.rb",
+     "lib/harvest/api/user_assignments.rb",
+     "lib/harvest/api/users.rb",
+     "lib/harvest/base.rb",
+     "lib/harvest/base_model.rb",
+     "lib/harvest/behavior/activatable.rb",
+     "lib/harvest/behavior/crud.rb",
+     "lib/harvest/client.rb",
+     "lib/harvest/contact.rb",
+     "lib/harvest/credentials.rb",
+     "lib/harvest/errors.rb",
+     "lib/harvest/expense.rb",
+     "lib/harvest/expense_category.rb",
+     "lib/harvest/hardy_client.rb",
+     "lib/harvest/project.rb",
+     "lib/harvest/rate_limit_status.rb",
+     "lib/harvest/task.rb",
+     "lib/harvest/task_assignment.rb",
+     "lib/harvest/time_entry.rb",
+     "lib/harvest/timezones.rb",
+     "lib/harvest/user.rb",
+     "lib/harvest/user_assignment.rb",
+     "lib/harvested.rb",
+     "spec/harvest/base_spec.rb",
+     "spec/harvest/credentials_spec.rb",
+     "spec/harvest/expense_spec.rb",
+     "spec/harvest/task_assignment_spec.rb",
+     "spec/harvest/time_entry_spec.rb",
+     "spec/harvest/user_assignment_spec.rb",
+     "spec/harvest/user_spec.rb",
+     "spec/spec.default.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/zmoazeni/harvested}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A Ruby Wrapper for the Harvest API http://www.getharvest.com/}
+  s.test_files = [
+    "spec/harvest/base_spec.rb",
+     "spec/harvest/credentials_spec.rb",
+     "spec/harvest/expense_spec.rb",
+     "spec/harvest/task_assignment_spec.rb",
+     "spec/harvest/time_entry_spec.rb",
+     "spec/harvest/user_assignment_spec.rb",
+     "spec/harvest/user_spec.rb",
+     "spec/spec_helper.rb",
+     "examples/basics.rb",
+     "examples/clear_account.rb",
+     "examples/task_assignments.rb",
+     "examples/user_assignments.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<cucumber>, [">= 0"])
+      s.add_development_dependency(%q<ruby-debug>, [">= 0"])
+      s.add_development_dependency(%q<fakeweb>, [">= 0"])
+      s.add_runtime_dependency(%q<httparty>, [">= 0"])
+      s.add_runtime_dependency(%q<happymapper>, [">= 0"])
+      s.add_runtime_dependency(%q<builder>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<cucumber>, [">= 0"])
+      s.add_dependency(%q<ruby-debug>, [">= 0"])
+      s.add_dependency(%q<fakeweb>, [">= 0"])
+      s.add_dependency(%q<httparty>, [">= 0"])
+      s.add_dependency(%q<happymapper>, [">= 0"])
+      s.add_dependency(%q<builder>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<cucumber>, [">= 0"])
+    s.add_dependency(%q<ruby-debug>, [">= 0"])
+    s.add_dependency(%q<fakeweb>, [">= 0"])
+    s.add_dependency(%q<httparty>, [">= 0"])
+    s.add_dependency(%q<happymapper>, [">= 0"])
+    s.add_dependency(%q<builder>, [">= 0"])
+  end
+end
+

data/lib/harvest/api/account.rb

@@ -1,6 +1,11 @@
 module Harvest
   module API
+    
+    # API Methods to contain all account actions
     class Account < Base
+      
+      # Returns the current rate limit information
+      # @return [Harvest::RateLimitStatus]
       def rate_limit_status
         response = request(:get, credentials, '/account/rate_limit_status')
         Harvest::RateLimitStatus.parse(response.body)

data/lib/harvest/api/base.rb

@@ -2,11 +2,11 @@ module Harvest
   module API
     class Base
       attr_reader :credentials
-    
+      
       def initialize(credentials)
         @credentials = credentials
       end
-    
+      
       class << self
         def api_model(klass)
           class_eval <<-END
@@ -16,7 +16,7 @@ module Harvest
           END
         end
       end
-    
+      
       protected
         def request(method, credentials, path, options = {})
           response = HTTParty.send(method, "#{credentials.host}#{path}", :query => options[:query], :body => options[:body], :headers => {"Accept" => "application/xml", "Content-Type" => "application/xml; charset=utf-8", "Authorization" => "Basic #{credentials.basic_auth}", "User-Agent" => "Harvestable/#{Harvest::VERSION}"}.update(options[:headers] || {}), :format => :plain)

data/lib/harvest/api/clients.rb

@@ -2,7 +2,7 @@ module Harvest
   module API
     class Clients < Base
       api_model Harvest::Client
-    
+      
       include Harvest::Behavior::Crud
       include Harvest::Behavior::Activatable
     end

data/lib/harvest/api/contacts.rb

@@ -11,7 +11,7 @@ module Harvest
         else
           request(:get, credentials, "/contacts")
         end
-      
+        
         api_model.parse(response.body)
       end
     end

data/lib/harvest/api/projects.rb

@@ -5,12 +5,23 @@ module Harvest
       
       include Harvest::Behavior::Crud
       
+      # Creates and Assigns a task to the project
+      #
+      # == Examples
+      #  project = harvest.projects.find(401)
+      #  harvest.projects.create_task(project, 'Bottling Glue') # creates and assigns a task to the project
+      #
+      # @return [Harvest::Project]
       def create_task(project, task_name)
         response = request(:post, credentials, "/projects/#{project.to_i}/task_assignments/add_with_create_new_task", :body => task_xml(task_name))
         id = response.headers["location"].first.match(/\/.*\/(\d+)\/.*\/(\d+)/)[1]
         find(id)
       end
       
+      # Deactivates the project. Does nothing if the project is already deactivated
+      # 
+      # @param [Harvest::Project] project the project you want to deactivate
+      # @return [Harvest::Project] the deactivated project
       def deactivate(project)
         if project.active?
           request(:put, credentials, "#{api_model.api_path}/#{project.to_i}/toggle", :headers => {'Content-Length' => '0'})
@@ -18,7 +29,11 @@ module Harvest
         end
         project
       end
-    
+      
+      # Activates the project. Does nothing if the project is already activated
+      # 
+      # @param [Harvest::Project] project the project you want to activate
+      # @return [Harvest::Project] the activated project
       def activate(project)
         if !project.active?
           request(:put, credentials, "#{api_model.api_path}/#{project.to_i}/toggle", :headers => {'Content-Length' => '0'})

data/lib/harvest/api/users.rb

@@ -5,7 +5,13 @@ module Harvest
     
       include Harvest::Behavior::Crud
       include Harvest::Behavior::Activatable
-    
+      
+      # Triggers Harvest to reset the user's password and sends them an email to change it.
+      # @overload reset_password(id)
+      #   @param [Integer] id the id of the user you want to reset the password for
+      # @overload reset_password(user)
+      #   @param [Harvest::User] user the user you want to reset the password for
+      # @return [Harvest::User] the user you passed in
       def reset_password(user)
         request(:post, credentials, "#{api_model.api_path}/#{user.to_i}/reset_password")
         user

data/lib/harvest/base.rb

@@ -2,48 +2,247 @@ module Harvest
   class Base
     attr_reader :request, :credentials
     
+    # @see Harvest.client
+    # @see Harvest.hardy_client
     def initialize(subdomain, username, password, options = {})
       options[:ssl] = true if options[:ssl].nil?
       @credentials = Credentials.new(subdomain, username, password, options[:ssl])
       raise InvalidCredentials unless credentials.valid?
     end
     
+    # All API actions surrounding accounts
+    #
+    # == Examples
+    #  harvest.account.rate_limit_status # Returns a Harvest::RateLimitStatus
+    #
+    # @return [Harvest::API::Account]
     def account
       @account ||= Harvest::API::Account.new(credentials)
     end
     
+    # All API Actions surrounding Clients
+    # 
+    # == Examples
+    #  harvest.clients.all() # Returns all clients in the system
+    #  
+    #  harvest.clients.find(100) # Returns the client with id = 100
+    #  
+    #  client = Harvest::Client.new(:name => 'SuprCorp')
+    #  saved_client = harvest.clients.create(client) # returns a saved version of Harvest::Client
+    #  
+    #  client = harvest.clients.find(205)
+    #  client.name = 'SuprCorp LTD.'
+    #  updated_client = harvest.clients.update(client) # returns an updated version of Harvest::Client
+    #  
+    #  client = harvest.clients.find(205)
+    #  harvest.clients.delete(client) # returns 205
+    #  
+    #  client = harvest.clients.find(301)
+    #  deactivated_client = harvest.clients.deactivate(client) # returns an updated deactivated client
+    #  activated_client = harvest.clients.activate(client) # returns an updated activated client
+    # 
+    # @see Harvest::Behavior::Crud
+    # @see Harvest::Behavior::Activatable
+    # @return [Harvest::API::Clients]
     def clients
       @clients ||= Harvest::API::Clients.new(credentials)
     end
     
+    # All API Actions surrounding Client Contacts
+    # 
+    # == Examples
+    #  harvest.contacts.all() # Returns all contacts in the system
+    #  harvest.contacts.all(10) # Returns all contacts for the client id=10 in the system
+    #  
+    #  harvest.contacts.find(100) # Returns the contact with id = 100
+    #  
+    #  contact = Harvest::Contact.new(:first_name => 'Jane', :last_name => 'Doe', :client_id => 10)
+    #  saved_contact = harvest.contacts.create(contact) # returns a saved version of Harvest::Contact
+    #  
+    #  contact = harvest.contacts.find(205)
+    #  contact.first_name = 'Jilly'
+    #  updated_contact = harvest.contacts.update(contact) # returns an updated version of Harvest::Contact
+    #  
+    #  contact = harvest.contacts.find(205)
+    #  harvest.contacts.delete(contact) # returns 205
+    # 
+    # @see Harvest::Behavior::Crud
+    # @return [Harvest::API::Contacts]
     def contacts
       @contacts ||= Harvest::API::Contacts.new(credentials)
     end
     
+    # All API Actions surrounding Projects
+    # 
+    # == Examples
+    #  harvest.projects.all() # Returns all projects in the system
+    #  
+    #  harvest.projects.find(100) # Returns the project with id = 100
+    #  
+    #  project = Harvest::Project.new(:name => 'SuprGlu' :client_id => 10)
+    #  saved_project = harvest.projects.create(project) # returns a saved version of Harvest::Project
+    #  
+    #  project = harvest.projects.find(205)
+    #  project.name = 'SuprSticky'
+    #  updated_project = harvest.projects.update(project) # returns an updated version of Harvest::Project
+    #  
+    #  project = harvest.project.find(205)
+    #  harvest.projects.delete(project) # returns 205
+    #  
+    #  project = harvest.projects.find(301)
+    #  deactivated_project = harvest.projects.deactivate(project) # returns an updated deactivated project
+    #  activated_project = harvest.projects.activate(project) # returns an updated activated project
+    #
+    #  project = harvest.projects.find(401)
+    #  harvest.projects.create_task(project, 'Bottling Glue') # creates and assigns a task to the project
+    #
+    # @see Harvest::Behavior::Crud
+    # @see Harvest::Behavior::Activatable
+    # @return [Harvest::API::Projects]
     def projects
       @projects ||= Harvest::API::Projects.new(credentials)
     end
     
+    # All API Actions surrounding Tasks
+    # 
+    # == Examples
+    #  harvest.tasks.all() # Returns all tasks in the system
+    #  
+    #  harvest.tasks.find(100) # Returns the task with id = 100
+    #  
+    #  task = Harvest::Task.new(:name => 'Server Administration' :default => true)
+    #  saved_task = harvest.tasks.create(task) # returns a saved version of Harvest::Task
+    #  
+    #  task = harvest.tasks.find(205)
+    #  task.name = 'Server Administration'
+    #  updated_task = harvest.tasks.update(task) # returns an updated version of Harvest::Task
+    #  
+    #  task = harvest.task.find(205)
+    #  harvest.tasks.delete(task) # returns 205
+    #   
+    # @see Harvest::Behavior::Crud
+    # @return [Harvest::API::Tasks]
     def tasks
       @tasks ||= Harvest::API::Tasks.new(credentials)
     end
     
+    # All API Actions surrounding Users
+    # 
+    # == Examples
+    #  harvest.users.all() # Returns all users in the system
+    #  
+    #  harvest.users.find(100) # Returns the user with id = 100
+    #  
+    #  user = Harvest::User.new(:first_name => 'Edgar', :last_name => 'Ruth', :email => 'edgar@ruth.com', :password => 'mypassword', :password_confirmation => 'mypassword', :timezone => :cst, :admin => false, :telephone => '444-4444')
+    #  saved_user = harvest.users.create(user) # returns a saved version of Harvest::User
+    #  
+    #  user = harvest.users.find(205)
+    #  user.email = 'edgar@ruth.com'
+    #  updated_user = harvest.users.update(user) # returns an updated version of Harvest::User
+    #  
+    #  user = harvest.users.find(205)
+    #  harvest.users.delete(user) # returns 205
+    #  
+    #  user = harvest.users.find(301)
+    #  deactivated_user = harvest.users.deactivate(user) # returns an updated deactivated user
+    #  activated_user = harvest.users.activate(user) # returns an updated activated user
+    #  
+    #  user = harvest.users.find(401)
+    #  harvest.users.reset_password(user) # will trigger the reset password feature of harvest and shoot the user an email
+    #   
+    # @see Harvest::Behavior::Crud
+    # @see Harvest::Behavior::Activatable
+    # @return [Harvest::API::Users]
     def users
       @users ||= Harvest::API::Users.new(credentials)
     end
     
+    # All API Actions surrounding assigning tasks to projects
+    # 
+    # == Examples
+    #  project = harvest.projects.find(101)
+    #  harvest.task_assignments.all(project) # returns all tasks assigned to the project  (as Harvest::TaskAssignment)
+    #  
+    #  project = harvest.projects.find(201)
+    #  harvest.task_assignments.find(project, 5) # returns the task assignment with ID 5 that is assigned to the project
+    #
+    #  project = harvest.projects.find(301)
+    #  task = harvest.tasks.find(100)
+    #  assignment = Harvest::TaskAssignment.new(:task_id => task.id, :project_id => project.id)
+    #  saved_assignment = harvest.task_assignments.create(assignment) # returns a saved version of the task assignment
+    #
+    #  project = harvest.projects.find(401)
+    #  assignment = harvest.task_assignments.find(project, 15)
+    #  assignment.hourly_rate = 150
+    #  updated_assignment = harvest.task_assignments.update(assignment) # returns an updated assignment
+    #
+    #  project = harvest.projects.find(501)
+    #  assignment = harvest.task_assignments.find(project, 25)
+    #  harvest.task_assignments.delete(assignment) # returns 25
+    #
+    # @return [Harvest::API::TaskAssignments]
     def task_assignments
       @task_assignments ||= Harvest::API::TaskAssignments.new(credentials)
     end
     
+    # All API Actions surrounding assigning users to projects
+    # 
+    # == Examples
+    #  project = harvest.projects.find(101)
+    #  harvest.user_assignments.all(project) # returns all users assigned to the project  (as Harvest::UserAssignment)
+    #  
+    #  project = harvest.projects.find(201)
+    #  harvest.user_assignments.find(project, 5) # returns the user assignment with ID 5 that is assigned to the project
+    #
+    #  project = harvest.projects.find(301)
+    #  user = harvest.users.find(100)
+    #  assignment = Harvest::UserAssignment.new(:user_id => user.id, :project_id => project.id)
+    #  saved_assignment = harvest.user_assignments.create(assignment) # returns a saved version of the user assignment
+    #
+    #  project = harvest.projects.find(401)
+    #  assignment = harvest.user_assignments.find(project, 15)
+    #  assignment.project_manager = true
+    #  updated_assignment = harvest.user_assignments.update(assignment) # returns an updated assignment
+    #
+    #  project = harvest.projects.find(501)
+    #  assignment = harvest.user_assignments.find(project, 25)
+    #  harvest.user_assignments.delete(assignment) # returns 25
+    #
+    # @return [Harvest::API::UserAssignments]
     def user_assignments
       @user_assignments ||= Harvest::API::UserAssignments.new(credentials)
     end
     
+    # All API Actions surrounding managing expense categories
+    #
+    # == Examples
+    #  harvest.expense_categories.all() # Returns all expense categories in the system
+    #  
+    #  harvest.expense_categories.find(100) # Returns the expense category with id = 100
+    #  
+    #  category = Harvest::ExpenseCategory.new(:name => 'Mileage', :unit_price => 0.485)
+    #  saved_category = harvest.expense_categories.create(category) # returns a saved version of Harvest::ExpenseCategory
+    #  
+    #  category = harvest.clients.find(205)
+    #  category.name = 'Travel'
+    #  updated_category = harvest.expense_categories.update(category) # returns an updated version of Harvest::ExpenseCategory
+    #  
+    #  category = harvest.expense_categories.find(205)
+    #  harvest.expense_categories.delete(category) # returns 205
+    #
+    # @see Harvest::Behavior::Crud
+    # @return [Harvest::API::ExpenseCategories]
     def expense_categories
       @expense_categories ||= Harvest::API::ExpenseCategories.new(credentials)
     end
     
+    # All API Actions surrounding expenses
+    #
+    # == Examples
+    #  harvest.expenses.all() # Returns all expenses for the current week
+    #  harvest.expenses.all(Time.parse('11/12/2009')) # returns all expenses for the week of 11/12/2009
+    #  
+    #  harvest.expenses.find(100) # Returns the expense with id = 100
     def expenses
       @expenses ||= Harvest::API::Expenses.new(credentials)
     end

data/lib/harvest/base_model.rb

@@ -1,21 +1,58 @@
 module Harvest
+  # The parent class of all Harvest models. Contains useful inheritable methods
   class BaseModel
+    
+    # Initializes the model. You can pass the attributes as a hash in a ActiveRecord-like style
+    #
+    # == Examples
+    #   client = Harvest::Client.new(:name => 'John Doe')
+    #   client.name # returns 'John Doe'
     def initialize(attributes = {})
       self.attributes = attributes
     end
-  
+    
+    # Given a hash, sets the corresponding attributes
+    #
+    # == Examples
+    #   client = Harvest::Client.new(:name => 'John Doe')
+    #   client.name # returns 'John Doe'
+    #   client.attributes = {:name => 'Terry Vaughn'}
+    #   client.name # returns 'Terry Vaughn'
+    #
+    # @return [void]
     def attributes=(attributes)
       attributes.each {|k,v| send("#{k}=", v)}
     end
-  
+    
+    # Checks the equality of another model based on the id
+    #
+    # == Examples
+    #  client1 = Harvest::Client.new(:id => 1)
+    #  client2 = Harvest::Client.new(:id => 1)
+    #  client3 = Harvest::Client.new(:id => 2)
+    #  
+    #  client1 == client2 # returns true
+    #  client1 == client3 # returns false
+    #
+    # @return [Boolean]
     def ==(other)
       id == other.id
     end
-  
+    
+    # Returns the id of the model
+    #
+    # == Examples
+    #  client = Harvest::Client.new(:id => 1)
+    #  client.to_i # returns 1
+    #
+    # @return [Fixnum]
     def to_i
       id
     end
-  
+    
+    # Builds the XML of the model. Primarily used to interact with the Harvest API.
+    # 
+    # @return [String]
     def to_xml
       builder = Builder::XmlMarkup.new
       builder.tag!(self.class.tag_name) do |c|
@@ -26,6 +63,8 @@ module Harvest
     end
   
     class << self
+      # This sets the API path so the API collections can use them in an agnostic way
+      # @return [void]
       def api_path(path = nil)
         @path ||= path
       end

data/lib/harvest/behavior/activatable.rb

@@ -1,6 +1,12 @@
 module Harvest
   module Behavior
+    
+    # Activate/Deactivate behaviors that can be brought into API collections
     module Activatable
+      # Deactivates the item. Does nothing if the item is already deactivated
+      # 
+      # @param [Harvest::BaseModel] model the model you want to deactivate
+      # @return [Harvest::BaseModel] the deactivated model
       def deactivate(model)
         if model.active?
           request(:post, credentials, "#{api_model.api_path}/#{model.to_i}/toggle")
@@ -8,7 +14,11 @@ module Harvest
         end
         model
       end
-    
+      
+      # Activates the item. Does nothing if the item is already activated
+      # 
+      # @param [Harvest::BaseModel] model the model you want to activate
+      # @return [Harvest::BaseModel] the activated model
       def activate(model)
         if !model.active?
           request(:post, credentials, "#{api_model.api_path}/#{model.to_i}/toggle")

data/lib/harvest/behavior/crud.rb

@@ -1,30 +1,56 @@
 module Harvest
   module Behavior
     module Crud
+      # Retrieves all items
+      # @return [Array<Harvest::BaseModel>] an array of models depending on where you're calling it from (e.g. [Harvest::Client] from Harvest::Base#clients)
       def all
         response = request(:get, credentials, api_model.api_path)
         api_model.parse(response.body)
       end
       
+      # Retrieves an item by id
+      # @overload find(id)
+      #   @param [Integer] the id of the item you want to retreive
+      # @overload find(id)
+      #   @param [String] id the String version of the id
+      # @overload find(model)
+      #   @param [Harvest::BaseModel] id you can pass a model and it will return a refreshed version
+      # 
+      # @return [Harvest::BaseModel] the model depends on where you're calling it from (e.g. Harvest::Client from Harvest::Base#clients)
       def find(id)
         response = request(:get, credentials, "#{api_model.api_path}/#{id}")
         api_model.parse(response.body, :single => true)
       end
       
+      # Creates an item
+      # @param [Harvest::BaseModel] model the item you want to create
+      # @return [Harvest::BaseModel] the created model depending on where you're calling it from (e.g. Harvest::Client from Harvest::Base#clients)
       def create(model)
         response = request(:post, credentials, "#{api_model.api_path}", :body => model.to_xml)
         id = response.headers["location"].first.match(/\/.*\/(\d+)/)[1]
         find(id)
       end
       
+      # Updates an item
+      # @param [Harvest::BaseModel] model the model you want to update
+      # @return [Harvest::BaseModel] the created model depending on where you're calling it from (e.g. Harvest::Client from Harvest::Base#clients)
       def update(model)
         request(:put, credentials, "#{api_model.api_path}/#{model.to_i}", :body => model.to_xml)
         find(model.id)
       end
       
+      # Deletes an item
+      # @overload delete(model)
+      #  @param [Harvest::BaseModel] model the item you want to delete
+      # @overload delete(id)
+      #  @param [Integer] id the id of the item you want to delete
+      # @overload delete(id)
+      #  @param [String] id the String version of the id of the item you want to delete
+      # 
+      # @return [Integer] the id of the item deleted
       def delete(model)
         request(:delete, credentials, "#{api_model.api_path}/#{model.to_i}")
-        model.id
+        model.to_i
       end
     end
   end

data/lib/harvest/client.rb

@@ -1,4 +1,15 @@
 module Harvest
+  # The model that contains information about a client
+  #
+  # == Fields
+  # [+id+] (READONLY) the id of the client
+  # [+name+] (REQUIRED) the name of the client
+  # [+details+] the details of the client
+  # [+currency+] what type of currency is associated with the client
+  # [+currency_symbol+] what currency symbol is associated with the client
+  # [+active?+] true|false on whether the client is active
+  # [+highrise_id+] (READONLY) the highrise id associated with this client
+  # [+update_at+] (READONLY) the last modification timestamp
   class Client < BaseModel
     include HappyMapper
   
@@ -12,7 +23,8 @@ module Harvest
     element :currency_symbol, String, :tag => "currency-symbol"
     element :cache_version, Integer, :tag => "cache-version"
     element :updated_at, Time, :tag => "updated-at"
-  
+    element :highrise_id, Integer, :tag => 'highrise-id'
+    
     alias_method :active?, :active
   end
 end

data/lib/harvest/contact.rb

@@ -1,4 +1,16 @@
 module Harvest
+  # The model that contains information about a client contact
+  #
+  # == Fields
+  # [+id+] (READONLY) the id of the contact
+  # [+client_id+] (REQUIRED) the id of the client this contact is associated with
+  # [+first_name+] (REQUIRED) the first name of the contact
+  # [+last_name+] (REQUIRED) the last name of the contact
+  # [+email+] the email of the contact
+  # [+title+] the title of the contact
+  # [+phone_office+] the office phone number of the contact
+  # [+phone_moble+] the moble phone number of the contact
+  # [+fax+] the fax number of the contact
   class Contact < BaseModel
     include HappyMapper
     
@@ -12,5 +24,6 @@ module Harvest
     element :phone_office, String, :tag => "phone-office"
     element :phone_mobile, String, :tag => "phone-mobile"
     element :fax, String
+    element :title, String
   end
 end

data/lib/harvest/project.rb

@@ -1,4 +1,27 @@
 module Harvest
+  
+  # The model that contains information about a project
+  #
+  # == Fields
+  # [+id+] (READONLY) the id of the project
+  # [+name+] (REQUIRED) the name of the project
+  # [+client_id+] (REQUIRED) the client id of the project
+  # [+code+] the project code
+  # [+notes+] the project notes
+  # [+active?+] true|false whether the project is active
+  # [+billable?+] true|false where the project is billable
+  # [+budget_by+] how the budget is calculated for the project +project|project_cost|task|person|nil+
+  # [+budget+] what the budget is for the project (based on budget_by)
+  # [+bill_by+] how to bill the project +Tasks|People|Project|nil+
+  # [+hourly_rate+] what the hourly rate for the project is based on +bill_by+
+  # [+notify_when_over_budget?+] whether the project will send notifications when it goes over budget
+  # [+over_budget_notification_percentage+] what percentage of the budget the project has to be before it sends a notification. Based on +notify_when_over_budget?+
+  # [+show_budget_to_all?+] whether the project's budget is shown to employees and contractors
+  # [+basecamp_id+] (READONLY) the id of the basecamp project associated to the project
+  # [+highrise_deal_id+] (READONLY) the id of the highrise deal associated to the project
+  # [+active_task_assignments_count+] (READONLY) the number of active task assignments
+  # [+created_at+] (READONLY) when the project was created
+  # [+updated_at+] (READONLY) when the project was updated
   class Project < BaseModel
     include HappyMapper
   
@@ -12,11 +35,22 @@ module Harvest
     element :fees, String
     element :active, Boolean
     element :billable, Boolean
-    element :budget, String
-    element :budget_by, Float, :tag => 'budget-by'
+    element :budget, Float
+    element :budget_by, String, :tag => 'budget-by'
     element :hourly_rate, Float, :tag => 'hourly-rate'
     element :bill_by, String, :tag => 'bill-by'
+    element :created_at, Time, :tag => 'created-at'
+    element :updated_at, Time, :tag => 'updated-at'
+    element :notify_when_over_budget, Boolean, :tag => 'notify-when-over-budget'
+    element :over_budget_notification_percentage, Float, :tag => 'over-budget-notification-percentage'
+    element :show_budget_to_all, Boolean, :tag => 'show-budget-to-all'
+    element :basecamp_id, Integer, :tag => 'basecamp-id'
+    element :highrise_deal_id, Integer, :tag => 'highrise-deal-id'
+    element :active_task_assignments_count, Integer, :tag => 'active-task-assignments-count'
   
     alias_method :active?, :active
+    alias_method :billable?, :billable
+    alias_method :notify_when_over_budget?, :notify_when_over_budget
+    alias_method :show_budget_to_all?, :show_budget_to_all
   end
 end

data/lib/harvest/rate_limit_status.rb

@@ -1,4 +1,13 @@
 module Harvest
+  
+  # The model that contains the information about the user's rate limit
+  #
+  # == Fields
+  # [+last_access_at+]  The last registered request
+  # [+count+] The current number of requests registered
+  # [+timeframe_limit+] The amount of seconds before a rate limit refresh occurs
+  # [+max_calls+] The number of requests you can make within the +timeframe_limit+
+  # [+lockout_seconds+] If you exceed the rate limit, how long you will be locked out from Harvest
   class RateLimitStatus < BaseModel
     include HappyMapper
     
@@ -9,6 +18,9 @@ module Harvest
     element :max_calls, Integer, :tag => 'max-calls'
     element :lockout_seconds, Integer, :tag => 'lockout-seconds'
     
+    # Returns true if the user is over their rate limit
+    # @return [Boolean]
+    # @see http://www.getharvest.com/api
     def over_limit?
       count > max_calls
     end

data/lib/harvest/task.rb

@@ -1,4 +1,14 @@
 module Harvest
+  
+  # The model that contains information about a task
+  #
+  # == Fields
+  # [+id+] (READONLY) the id of the task
+  # [+name+] (REQUIRED) the name of the task
+  # [+billable+] whether the task is billable by default
+  # [+deactivated+] whether the task is deactivated
+  # [+hourly_rate+] what the default hourly rate for the task is
+  # [+default?+] whether to add this task to new projects by default
   class Task < BaseModel
     include HappyMapper
   

data/lib/harvest/timezones.rb

@@ -1,6 +1,5 @@
-# shamelessly ripped from Rails: http://github.com/rails/rails/blob/master/activesupport/lib/active_support/values/time_zone.rb
-
 module Harvest
+  # shamelessly ripped from Rails: http://github.com/rails/rails/blob/master/activesupport/lib/active_support/values/time_zone.rb
   module Timezones
     MAPPING = {
         "pacific/midway"                  =>   "International Date Line West",

data/lib/harvest/user.rb

@@ -1,7 +1,24 @@
 module Harvest
+  
+  # The model that contains information about a task
+  #
+  # == Fields
+  # [+id+] (READONLY) the id of the user
+  # [+email+] the email of the user
+  # [+first_name+] the first name for the user
+  # [+last_name+] the last name for the user
+  # [+telephone+] the telephone for the user
+  # [+department] the department for the user
+  # [+password|password_confirmation+] the password for the user (only used on create.)
+  # [+has_access_to_all_future_projects+] whether the user should be added to future projects by default
+  # [+hourly_rate+] what the default hourly rate for the user is
+  # [+admin?+] whether the user is an admin
+  # [+contractor?+] whether the user is a contractor
+  # [+contractor?+] whether the user is a contractor
+  # [+timezone+] the timezone for the user.
   class User < BaseModel
     include HappyMapper
-  
+    
     api_path '/people'
     element :id, Integer
     element :email, String
@@ -13,14 +30,23 @@ module Harvest
     element :admin, Boolean, :tag => 'is-admin'
     element :contractor, Boolean, :tag => 'is-contractor'
     element :telephone, String
+    element :department, String
     element :timezone, String
     element :password, String
     element :password_confirmation, String, :tag => 'password-confirmation'
-  
+    
     alias_method :active?, :active
     alias_method :admin?, :admin
     alias_method :contractor?, :contractor
-  
+    
+    # Sets the timezone for the user. This can be done in a variety of ways.
+    # 
+    # == Examples
+    #   user.timezone = :cst # the easiest way. CST, EST, MST, and PST are supported
+    #   
+    #   user.timezone = 'america/chicago' # a little more verbose
+    #   
+    #   user.timezone = 'Central Time (US & Canada)' # the most explicit way
     def timezone=(timezone)
       tz = timezone.to_s.downcase
       case tz

data/lib/harvested.rb

@@ -16,13 +16,44 @@ require 'harvest/base'
 %w(base account clients contacts projects tasks users task_assignments user_assignments expense_categories expenses time reports).each {|a| require "harvest/api/#{a}"}
 
 module Harvest
-  VERSION = "0.3.0".freeze
+  VERSION = "0.3.1".freeze
   
   class << self
+    
+    # Creates a standard client that will raise all errors it encounters
+    #
+    # == Options
+    # * +:ssl+ - Whether or not to use SSL when connecting to Harvest. This is dependent on whether your account supports it. Set to +true+ by default
+    # == Examples
+    #   Harvest.client('mysubdomain', 'myusername', 'mypassword', :ssl => false)
+    #
+    # @return [Harvest::Base]
     def client(subdomain, username, password, options = {})
       Harvest::Base.new(subdomain, username, password, options)
     end
     
+    # Creates a hardy client that will retry common HTTP errors it encounters and sleep() if it determines it is over your rate limit
+    #
+    # == Options
+    # * +:ssl+ - Whether or not to use SSL when connecting to Harvest. This is dependent on whether your account supports it. Set to +true+ by default
+    # * +:retry+ - How many times the hardy client should retry errors. Set to +5+ by default.
+    #
+    # == Examples
+    #   Harvest.hardy_client('mysubdomain', 'myusername', 'mypassword', :ssl => true, :retry => 3)
+    #
+    # == Errors
+    # The hardy client will retry the following errors
+    # * Harvest::Unavailable
+    # * Harvest::InformHarvest
+    # * Net::HTTPError
+    # * Net::HTTPFatalError
+    # * Errno::ECONNRESET
+    #
+    # == Rate Limits
+    # The hardy client will make as many requests as it can until it detects it has gone over the rate limit. Then it will +sleep()+ for the how ever long it takes for the limit to reset. You can find more information about the Rate Limiting at http://www.getharvest.com/api
+    #
+    # @return [Harvest::HardyClient] a Harvest::Base wrapped in a Harvest::HardyClient
+    # @see Harvest::Base
     def hardy_client(subdomain, username, password, options = {})
       retries = options.delete(:retry)
       Harvest::HardyClient.new(client(subdomain, username, password, options), (retries || 5))

data/spec/spec_helper.rb

@@ -1,7 +1,7 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require "rubygems"
-require 'harvest'
+require 'harvested'
 require 'spec'
 require 'spec/autorun'
 

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: harvested
 version: !ruby/object:Gem::Version 
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 3
-  - 0
-  version: 0.3.0
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Zach Moazeni
@@ -14,16 +15,18 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-11 00:00:00 -04:00
+date: 2010-10-14 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 13
         segments: 
         - 1
         - 2
@@ -35,9 +38,11 @@ dependencies:
   name: cucumber
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -47,9 +52,11 @@ dependencies:
   name: ruby-debug
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -59,9 +66,11 @@ dependencies:
   name: fakeweb
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -71,9 +80,11 @@ dependencies:
   name: httparty
   prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -83,9 +94,11 @@ dependencies:
   name: happymapper
   prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -95,15 +108,17 @@ dependencies:
   name: builder
   prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
   type: :runtime
   version_requirements: *id007
-description: Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found at http://www.getharvest.com/api
+description: Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found on their website (http://www.getharvest.com/api). For support hit up the Mailing List (http://groups.google.com/group/harvested)
 email: zach.moazeni@gmail.com
 executables: []
 
@@ -112,6 +127,7 @@ extensions: []
 extra_rdoc_files: 
 - README.md
 files: 
+- .document
 - .gitignore
 - HISTORY
 - MIT-LICENSE
@@ -156,6 +172,7 @@ files:
 - features/time_tracking.feature
 - features/user_assignments.feature
 - features/users.feature
+- harvested.gemspec
 - lib/harvest/api/account.rb
 - lib/harvest/api/base.rb
 - lib/harvest/api/clients.rb
@@ -208,23 +225,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: A Ruby Wrapper for the Harvest API http://www.getharvest.com/