harv 0.8.3

data/HISTORY

@@ -0,0 +1,3 @@
+0.8 (December 10, 2008)
+  First version
+

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2008, Kyle Banker, Alexander Interactive, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+Except as contained in this notice, the name(s) of the above copyright holders 
+shall not be used in advertising or otherwise to promote the sale, use or other 
+dealings in this Software without prior written authorization.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +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
+
+=== 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

data/Rakefile

@@ -0,0 +1,44 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require './lib/harvest.rb'
+
+desc 'Default: run all tests.'
+task :default => :test_all
+
+namespace :test do
+
+  Rake::TestTask.new(:resources) do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/unit/resources/*_test.rb'
+    t.verbose = false
+  end
+  
+  Rake::TestTask.new(:base) do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/unit/*_test.rb'
+    t.verbose = false
+  end
+  
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/integration/*_test.rb'
+    t.verbose = false
+  end
+
+end
+
+desc "Test everything."
+task :test_all do
+  errors = %w(test:resources test:base).collect do |task|
+    begin
+      Rake::Task[task].invoke
+      nil
+    rescue => e
+      task
+    end
+  end.compact
+  abort "Errors running #{errors.to_sentence}!" if errors.any?
+end

data/lib/harvest/base.rb

@@ -0,0 +1,118 @@
+module Harvest
+  class Base
+    @debug_level = 0
+
+    def self.debug_level
+      @debug_level
+    end
+    
+    def self.debug_level=(debug_level)
+      raise ArgumentError, "debug level must be an integer" unless debug_level == debug_level.to_i
+
+      return @debug_level if @debug_level == debug_level
+
+      @debug_level = debug_level.to_i
+
+      ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+
+      case @debug_level
+      when 0 then
+      when 1 then
+        @subscriber = ActiveSupport::Notifications.subscribe(/request.active_resource/) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          puts "-- HARVEST #{event.payload[:method].to_s.upcase} #{event.payload[:request_uri]}, #{event.payload[:result].andand.code}: #{event.payload[:result].andand.message}"
+        end
+      else
+        @subscriber = ActiveSupport::Notifications.subscribe(/request.active_resource/) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          puts "-- HARVEST #{event.payload[:method].to_s.upcase} #{event.payload[:request_uri]}, #{event.payload[:result].andand.code}: #{event.payload[:result].andand.message}"
+          puts event.payload[:result].body + "\n"
+        end
+      end
+      
+      @debug_level
+    end
+   
+    # Requires a sub_domain, email, and password.
+    # Specifying headers is optional, but useful for setting a user agent.
+    def initialize(options={})
+      options.assert_required_keys(:email, :password, :sub_domain)
+      @email        = options[:email]
+      @password     = options[:password]
+      @sub_domain   = options[:sub_domain]
+      @headers      = options[:headers]
+      @ssl          = options[:ssl]
+      configure_base_resource
+    end
+    
+    # Below is a series of proxies allowing for easy
+    # access to the various resources.
+    
+    # Clients
+    def clients
+      Harvest::Resources::Client
+    end
+
+    # Contacts
+    def contacts
+      Harvest::Resources::Contact
+    end
+    
+    # Expenses.
+    def expenses
+      Harvest::Resources::Expense
+    end
+    
+    # Expense categories.
+    def expense_categories
+      Harvest::Resources::ExpenseCategory
+    end
+    
+    # People.
+    # Also provides access to time entries.
+    def people
+      Harvest::Resources::Person
+    end
+    
+    # Projects.
+    # Provides access to the assigned users and tasks
+    # along with reports for entries on the project.
+    def projects
+      Harvest::Resources::Project
+    end
+    
+    # Tasks.
+    def tasks
+      Harvest::Resources::Task
+    end
+
+    # Invoices
+    def invoices
+      Harvest::Resources::Invoice
+    end
+
+    # Invoice Messages
+    def invoice_messages
+      Harvest::Resources::InvoiceMessage
+    end
+
+    private
+    
+      # Configure resource base class so that 
+      # inherited classes can access the api.
+      def configure_base_resource
+        HarvestResource.site     = "http#{'s' if @ssl}://#{@sub_domain}.#{Harvest::ApiDomain}"
+        HarvestResource.user     = @email
+        HarvestResource.password = @password
+        HarvestResource.headers.update(@headers) if @headers.is_a?(Hash)
+        load_resources
+      end
+      
+      # Load the classes representing the various resources.
+      def load_resources
+        resource_path = File.join(File.dirname(__FILE__), "resources")
+        Harvest.load_all_ruby_files_from_path(resource_path)
+      end
+                
+  end
+end

data/lib/harvest/harvest_resource.rb

@@ -0,0 +1,15 @@
+module Harvest
+  # This is the base class from which all resource
+  # classes inherit. Site and authentication params
+  # are loaded into this class when a Harvest::Base
+  # object is initialized.
+  class HarvestResource < ActiveResource::Base
+    include ActiveResourceThrottle
+    include Harvest::Plugins::ActiveResourceInheritableHeaders
+    
+    # The harvest api will block requests in excess
+    # of 40 / 15 seconds. Adds a throttle (with cautious settings). 
+    # Throttle feature provided by activeresource_throttle gem.
+    self.throttle(:requests => 30, :interval => 15, :sleep_interval => 60)
+  end
+end

data/lib/harvest/plugins/active_resource_inheritable_headers.rb

@@ -0,0 +1,36 @@
+# Allows headers in an ActiveResource::Base class
+# to be inherited by subclasses.  Useful for setting
+# a User-Agent used by all resources.
+module Harvest
+  module Plugins
+    module ActiveResourceInheritableHeaders
+        
+      module ClassMethods
+        
+        # If headers are not defined in a
+        # given subclass, then obtain headers
+        # from the superclass.
+        def inheritable_headers
+          if defined?(@headers)
+            @headers
+          elsif superclass != Object && superclass.headers
+            superclass.headers
+          else
+            @headers ||= {}
+          end
+        end
+        
+      end
+      
+      def self.included(klass)
+        klass.instance_eval do
+          klass.extend ClassMethods
+          class << self
+            alias_method :headers, :inheritable_headers
+          end
+        end
+      end
+    
+    end
+  end
+end

data/lib/harvest/plugins/toggleable.rb

@@ -0,0 +1,12 @@
+# Adds toggability to a harvest resource.
+module Harvest
+  module Plugins
+    module Toggleable
+        
+      def toggle
+        put(:toggle)
+      end
+    
+    end
+  end
+end

data/lib/harvest/resources/client.rb

@@ -0,0 +1,34 @@
+module Harvest
+  module Resources
+    class Client < Harvest::HarvestResource
+      include Harvest::Plugins::Toggleable
+
+      def invoices(refresh = false)
+        if not refresh and @invoices
+          @invoices
+        else
+          page, @invoices = 1, []
+          begin
+            set = Invoice.find(:all, :params => {:client => self.id, :page => page })
+            puts "Found #{set.length.to_s} invoices" if Harvest::Base.debug_level == 2
+            @invoices += set
+            page +=1
+          end while set.length == 50
+          @invoices
+        end
+      end
+
+      def balance
+        invoices.select {|invoice| invoice.sent? }.inject(0) {|total, invoice| total + invoice.balance}
+      end
+      
+      def invoiced_amount
+        invoices.select {|invoice| invoice.sent? }.inject(0) {|total, invoice| total + invoice.amount}
+      end
+      
+      def paid_amount
+        invoices.select {|invoice| invoice.sent? }.inject(0) {|total, invoice| total + invoice.paid_amount}
+      end
+    end
+  end
+end

data/lib/harvest/resources/entry.rb

@@ -0,0 +1,34 @@
+# The entry resource is never accessed directly;
+# rather, it is manipulated through an instance
+# of Project or Person.
+module Harvest
+  module Resources
+    class Entry < Harvest::HarvestResource
+      
+      self.element_name = "entry"
+
+      class << self
+        
+        def project_id=(id)
+          @project_id = id
+          self.site = self.site + "/projects/#{@project_id}"
+        end
+        
+        def project_id
+          @project_id
+        end
+        
+        def person_id=(id)
+          @person_id = id
+          self.site = self.site + "/people/#{@person_id}"
+        end
+        
+        def person_id
+          @person_id
+        end
+        
+      end
+                  
+    end
+  end
+end

data/lib/harvest/resources/expense.rb

@@ -0,0 +1,22 @@
+module Harvest
+  module Resources
+    class Expense < Harvest::HarvestResource
+      
+      self.element_name = "expense"
+      
+      class << self
+      
+        def person_id=(id)
+          @person_id = id
+          self.site = self.site + "/people/#{@person_id}"
+        end
+        
+        def person_id
+          @person_id
+        end
+        
+      end
+                  
+    end
+  end
+end

data/lib/harvest/resources/expense_category.rb

@@ -0,0 +1,7 @@
+module Harvest
+  module Resources
+    class ExpenseCategory < Harvest::HarvestResource
+      
+    end
+  end
+end

data/lib/harvest/resources/person.rb

@@ -0,0 +1,44 @@
+module Harvest
+  module Resources
+    class Person < Harvest::HarvestResource
+      include Harvest::Plugins::Toggleable
+      
+      # Find all entries for the given person;
+      # options[:from] and options[:to] are required;
+      # include options[:user_id] to limit by a specific project.
+      def entries(options={})
+        validate_options(options)
+        entry_class = Harvest::Resources::Entry.clone
+        entry_class.person_id = self.id
+        entry_class.find :all, :params => format_params(options)
+      end
+      
+      def expenses(options={})
+        validate_options(options)
+        expense_class = Harvest::Resources::Expense.clone
+        expense_class.person_id = self.id
+        expense_class.find :all, :params => format_params(options)
+      end
+      
+      private
+      
+        def validate_options(options)
+          if [:from, :to].any? {|key| !options[key].respond_to?(:strftime) }
+            raise ArgumentError, "Must specify :from and :to as dates."
+          end
+          
+          if options[:from] > options[:to]
+            raise ArgumentError, ":start must precede :end."
+          end
+        
+        end
+        def format_params(options)
+          ops = { :from => options[:from].strftime("%Y%m%d"),
+                  :to   => options[:to].strftime("%Y%m%d")}
+          ops[:project_id] = options[:project_id] if options[:project_id]
+          return ops
+        end
+      
+    end
+  end
+end

data/lib/harvest/resources/project.rb

@@ -0,0 +1,51 @@
+module Harvest
+  module Resources
+    # Supports the following:
+    class Project < Harvest::HarvestResource
+      include Harvest::Plugins::Toggleable
+      
+      def users
+        user_class = Harvest::Resources::UserAssignment.clone
+        user_class.project_id = self.id
+        user_class
+      end
+      
+      def tasks
+        task_class = Harvest::Resources::TaskAssignment.clone
+        task_class.project_id = self.id
+        task_class
+      end
+      
+      # Find all entries for the given project;
+      # options[:from] and options[:to] are required;
+      # include options[:user_id] to limit by a specific user.
+      #   
+      def entries(options={})
+        validate_entries_options(options)
+        entry_class = Harvest::Resources::Entry.clone
+        entry_class.project_id = self.id
+        entry_class.find :all, :params => format_params(options)
+      end
+      
+      private
+      
+        def validate_entries_options(options)
+          if [:from, :to].any? {|key| !options[key].respond_to?(:strftime) }
+            raise ArgumentError, "Must specify :from and :to as dates."
+          end
+          
+          if options[:from] > options[:to]
+            raise ArgumentError, ":start must precede :end."
+          end
+        end
+        
+        def format_params(options)
+          ops = { :from => options[:from].strftime("%Y%m%d"),
+                  :to   => options[:to].strftime("%Y%m%d")}
+          ops[:user_id] = options[:user_id] if options[:user_id]
+          return ops
+        end
+          
+    end
+  end
+end

data/lib/harvest/resources/task.rb

@@ -0,0 +1,8 @@
+module Harvest
+  module Resources
+    class Task < Harvest::HarvestResource
+      include Harvest::Plugins::Toggleable
+                  
+    end
+  end
+end

data/lib/harvest/resources/task_assignment.rb

@@ -0,0 +1,27 @@
+# This class is accessed by an instance of Project.
+module Harvest
+  module Resources
+    class TaskAssignment < Harvest::HarvestResource
+            
+      self.element_name = "task_assignment"
+      
+      class << self
+        
+        def project_id=(id)
+          @project_id = id
+          set_site
+        end
+        
+        def project_id
+          @project_id
+        end
+        
+        def set_site
+          self.site = self.site + "/projects/#{self.project_id}"
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/harvest/resources/user_assignment.rb

@@ -0,0 +1,27 @@
+# This class is accessed by an instance of Project.
+module Harvest
+  module Resources
+    class UserAssignment < Harvest::HarvestResource
+            
+      self.element_name = "user_assignment"
+      
+      class << self
+        
+        def project_id=(id)
+          @project_id = id
+          set_site
+        end
+        
+        def project_id
+          @project_id
+        end
+        
+        def set_site
+          self.site = self.site + "/projects/#{self.project_id}"
+        end
+        
+      end
+      
+    end
+  end
+end