quilted-harvested 0.3.1

data/lib/harvest/api/time.rb

@@ -0,0 +1,32 @@
+module Harvest
+  module API
+    class Time < Base
+      
+      def find(id)
+        response = request(:get, credentials, "/daily/show/#{id}")
+        Harvest::TimeEntry.parse(response.body, :single => true)
+      end
+      
+      def all(date = ::Time.now)
+        date = ::Time.parse(date) if String === date
+        response = request(:get, credentials, "/daily/#{date.yday}/#{date.year}")
+        Harvest::TimeEntry.parse(response.body)
+      end
+      
+      def create(entry)
+        response = request(:post, credentials, '/daily/add', :body => entry.to_xml)
+        Harvest::TimeEntry.parse(response.body).first
+      end
+      
+      def update(entry)
+        request(:put, credentials, "/daily/update/#{entry.to_i}", :body => entry.to_xml)
+        find(entry.id)
+      end
+      
+      def delete(entry)
+        request(:delete, credentials, "/daily/delete/#{entry.to_i}")
+        entry.id
+      end
+    end
+  end
+end

data/lib/harvest/api/user_assignments.rb

@@ -0,0 +1,32 @@
+module Harvest
+  module API
+    class UserAssignments < Base
+      
+      def all(project)
+        response = request(:get, credentials, "/projects/#{project.to_i}/user_assignments")
+        Harvest::UserAssignment.parse(response.body)
+      end
+      
+      def find(project, id)
+        response = request(:get, credentials, "/projects/#{project.to_i}/user_assignments/#{id}")
+        Harvest::UserAssignment.parse(response.body, :single => true)
+      end
+      
+      def create(user_assignment)
+        response = request(:post, credentials, "/projects/#{user_assignment.project_id}/user_assignments", :body => user_assignment.user_xml)
+        id = response.headers["location"].first.match(/\/.*\/(\d+)\/.*\/(\d+)/)[2]
+        find(user_assignment.project_id, id)
+      end
+      
+      def update(user_assignment)
+        request(:put, credentials, "/projects/#{user_assignment.project_id}/user_assignments/#{user_assignment.id}", :body => user_assignment.to_xml)
+        find(user_assignment.project_id, user_assignment.id)
+      end
+      
+      def delete(user_assignment)
+        request(:delete, credentials, "/projects/#{user_assignment.project_id}/user_assignments/#{user_assignment.to_i}")
+        user_assignment.id
+      end
+    end
+  end
+end

data/lib/harvest/api/users.rb

@@ -0,0 +1,21 @@
+module Harvest
+  module API
+    class Users < Base
+      api_model Harvest::User
+    
+      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
+      end
+    end
+  end
+end

data/lib/harvest/base.rb

@@ -0,0 +1,258 @@
+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
+    
+    def time
+      @time ||= Harvest::API::Time.new(credentials)
+    end
+    
+    def reports
+      @reports ||= Harvest::API::Reports.new(credentials)
+    end
+  end
+end

data/lib/harvest/base_model.rb

@@ -0,0 +1,73 @@
+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|
+        self.class.elements.each do |f|
+          c.tag!(f.tag, send(f.name)) if send(f.name)
+        end
+      end
+    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
+    end
+  end
+end

data/lib/harvest/behavior/activatable.rb

@@ -0,0 +1,31 @@
+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")
+          model.active = false
+        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")
+          model.active = true
+        end
+        model
+      end
+    end
+  end
+end

data/lib/harvest/behavior/crud.rb

@@ -0,0 +1,57 @@
+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.to_i
+      end
+    end
+  end
+end

data/lib/harvest/client.rb

@@ -0,0 +1,30 @@
+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
+  
+    api_path '/clients'
+  
+    element :id, Integer
+    element :active, Boolean
+    element :name, String
+    element :details, String
+    element :currency, String
+    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

@@ -0,0 +1,29 @@
+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
+    
+    api_path '/contacts'
+    
+    element :id, Integer
+    element :client_id, Integer, :tag => "client-id"
+    element :email, String
+    element :first_name, String, :tag => "first-name"
+    element :last_name, String, :tag => "last-name"
+    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/credentials.rb

@@ -0,0 +1,21 @@
+module Harvest
+  class Credentials
+    attr_accessor :subdomain, :username, :password, :ssl
+    
+    def initialize(subdomain, username, password, ssl = true)
+      @subdomain, @username, @password, @ssl = subdomain, username, password, ssl
+    end
+    
+    def valid?
+      !subdomain.nil? && !username.nil? && !password.nil?
+    end
+    
+    def basic_auth
+      Base64.encode64("#{username}:#{password}").delete("\r\n")
+    end
+    
+    def host
+      "#{ssl ? "https" : "http"}://#{subdomain}.harvestapp.com"
+    end
+  end
+end

data/lib/harvest/errors.rb

@@ -0,0 +1,23 @@
+module Harvest
+  class InvalidCredentials < StandardError; end
+  
+  class HTTPError < StandardError
+    attr_reader :response
+    def initialize(response)
+      @response = response
+      super
+    end
+    
+    def to_s
+      hint = response.headers["hint"].nil? ? nil : response.headers["hint"].first
+      "#{self.class.to_s} : #{response.code}#{" - #{hint}" if hint}"
+    end
+  end
+  
+  class RateLimited < HTTPError; end
+  class NotFound < HTTPError; end
+  class Unavailable < HTTPError; end
+  class InformHarvest < HTTPError; end
+  class BadRequest < HTTPError; end
+  class ServerError < HTTPError; end
+end

data/lib/harvest/expense.rb

@@ -0,0 +1,19 @@
+module Harvest
+  class Expense < BaseModel
+    include HappyMapper
+  
+    api_path '/expenses'
+  
+    element :id, Integer
+    element :notes, String
+    element :units, Integer
+    element :total_cost, Float, :tag => 'total-cost'
+    element :project_id, Integer, :tag => 'project-id'
+    element :expense_category_id, Integer, :tag => 'expense-category-id'
+    element :spent_at, Time, :tag => 'spent-at'
+    
+    def spent_at=(date)
+      @spent_at = (String === date ? Time.parse(date) : date)
+    end
+  end
+end

data/lib/harvest/expense_category.rb

@@ -0,0 +1,18 @@
+module Harvest
+  class ExpenseCategory < BaseModel
+    include HappyMapper
+    
+    tag 'expense-category'
+    api_path '/expense_categories'
+    
+    element :id, Integer
+    element :name, String
+    element :unit_name, String, :tag => 'unit-name'
+    element :unit_price, Float, :tag => 'unit-price'
+    element :deactivated, Boolean
+    
+    def active?
+      !deactivated
+    end
+  end
+end