cashboard 1.0.1

data/lib/cashboard/behaviors/toggleable.rb

@@ -0,0 +1,18 @@
+# Standard interface to toggle the status of something between Active
+# and Closed inside Cashboard.
+module Cashboard::Behaviors::Toggleable
+  # Toggles status of the project between active/closed
+  # and sets appropriate variable.
+  def toggle_status
+    options = self.class.merge_options()
+    options.merge!({:body => self.to_xml})
+    response = self.class.put(self.links[:toggle_status], options)
+    begin 
+      self.class.check_status_code(response)
+    rescue
+      return false
+    end
+    self.is_active = !self.is_active
+    return true
+  end
+end

data/lib/cashboard/client_company.rb

@@ -0,0 +1,25 @@
+module Cashboard
+  class ClientCompany < Base
+    element :name
+    element :address
+    element :address2
+    element :city
+    element :state
+    element :zip
+    element :country_code
+    element :url
+    element :telephone
+    element :currency_type_code
+    element :notes
+    element :custom_1
+    element :custom_2
+    element :custom_3
+    
+    # Returns all associated CompanyMemberships
+    def memberships(options={})
+      self.class.get_collection(
+        self.links[:memberships], Cashboard::CompanyMembership, options
+      )
+    end
+  end
+end

data/lib/cashboard/client_contact.rb

@@ -0,0 +1,32 @@
+module Cashboard
+  class ClientContact < Base
+    element :api_key
+    element :last_login, DateTime
+    element :login_count, Integer
+    element :address
+    element :address2
+    element :city
+    element :country_code
+    element :currency_type_code
+    element :custom_1
+    element :custom_2
+    element :custom_3
+    element :email_address
+    element :first_name
+    element :last_name
+    element :notes
+    element :password
+    element :state
+    element :telephone
+    element :url
+    element :zip
+    
+    # Returns all associated CompanyMemberships
+    def memberships(options={})
+      self.class.get_collection(
+        self.links[:memberships], Cashboard::CompanyMembership, options
+      )
+    end
+    
+  end
+end

data/lib/cashboard/company_membership.rb

@@ -0,0 +1,6 @@
+module Cashboard
+  class CompanyMembership < Base
+    element :person_id
+    element :company_id
+  end
+end

data/lib/cashboard/document_template.rb

@@ -0,0 +1,10 @@
+module Cashboard
+  class DocumentTemplate < Base
+    element :content
+    element :created_at, DateTime
+    element :has_been_modified, Boolean
+    element :is_default, Boolean
+    element :name
+    element :title
+  end
+end

data/lib/cashboard/employee.rb

@@ -0,0 +1,29 @@
+module Cashboard
+  class Employee < Base
+    STATUS_CODES = {
+      :employee => 0,
+      :administrator => 2
+    }
+    
+    element :api_key, String
+    element :last_login, DateTime
+    element :login_count, Integer
+    element :address
+    element :address2
+    element :city
+    element :country_code
+    element :custom_1
+    element :custom_2
+    element :custom_3
+    element :email_address
+    element :employee_status_code, Integer
+    element :first_name
+    element :last_name
+    element :notes
+    element :password
+    element :state
+    element :telephone
+    element :url
+    element :zip
+  end
+end

data/lib/cashboard/errors.rb

@@ -0,0 +1,48 @@
+module Cashboard
+  class Unauthorized < StandardError; end
+  
+  class HTTPError < StandardError
+    attr_reader :response
+    def initialize(response)
+      @response = response
+      super
+    end
+    
+    def to_s
+      
+      #hint = response.response.body.nil? ? nil : response.response.body
+      #"#{self.class.to_s} : #{response.code}#{" - #{hint}" if hint}"
+      response.inspect
+    end
+  end
+  
+  class Forbidden < HTTPError; end
+  class RateLimited < HTTPError; end
+  class NotFound < HTTPError; end
+  class PaymentRequired < HTTPError; end
+  class Unavailable < HTTPError; end
+  class ServerError < HTTPError; end
+  
+  class BadRequest < HTTPError
+    # Custom parses our "errors" return XML
+    def to_s
+      response.response.body 
+    end
+    
+    # Returns a hash of errors keyed on field name.
+    # 
+    # Example
+    # {
+    #   :field_name_one => "Error message",
+    #   :field_name_two => "Error message"
+    # }
+    def errors
+      parsed_errors = XmlSimple.xml_in(response.response.body)
+      error_hash = {}
+      parsed_errors['error'].each do |e|
+        error_hash[e['field']] = e['content']
+      end
+      return error_hash
+    end
+  end
+end

data/lib/cashboard/estimate.rb

@@ -0,0 +1,43 @@
+module Cashboard
+  class Estimate < Base
+    include Cashboard::Behaviors::Toggleable
+    include Cashboard::Behaviors::ListsLineItems
+    
+    element :assigned_id
+    element :agreement_text
+    element :client_id
+    element :client_type
+    element :created_on, DateTime
+    element :deposit_amount, Float
+    element :discount_percentage, Float
+    element :document_template_id
+    element :has_been_sent, Boolean
+    element :intro_text
+    element :is_active, Boolean
+    element :name
+    element :requires_agreement, Boolean
+    element :sales_tax, Float
+    element :sales_tax_2, Float
+    element :sales_tax_2_cumulative, Boolean
+    # Read only attributes. Can't set these via API
+    element :discount_best, Float
+    element :discount_worst, Float
+    element :item_actual_best, Float
+    element :item_actual_worst, Float
+    element :item_cost_best, Float
+    element :item_cost_worst, Float
+    element :item_profit_best, Float
+    element :item_profit_worst, Float
+    element :item_taxable_best, Float
+    element :item_taxable_worst, Float
+    element :price_best, Float
+    element :price_worst, Float
+    element :tax_cost_best, Float
+    element :tax_cost_worst, Float
+    element :tax_cost_2_best, Float
+    element :tax_cost_2_worst, Float
+    element :time_best, Float
+    element :time_worst, Float
+     
+  end
+end

data/lib/cashboard/expense.rb

@@ -0,0 +1,14 @@
+module Cashboard
+  class Expense < Base
+    element :amount, Float
+    element :category
+    element :created_on, DateTime
+    element :description
+    element :invoice_line_item_id # read only
+    element :is_billable, Boolean
+    element :payee_id
+    element :payee_type
+    element :person_id
+    element :project_id
+  end
+end

data/lib/cashboard/invoice.rb

@@ -0,0 +1,75 @@
+module Cashboard
+  class Invoice < Base
+    element :assigned_id
+    element :balance, Float # readonly
+    element :client_id
+    element :client_type
+    element :created_on, DateTime
+    element :discount, Float # readonly
+    element :discount_percentage, Float
+    element :document_template_id
+    element :due_date, Date
+    element :early_period_in_days, Integer
+    element :has_been_sent, Boolean
+    element :include_expenses, Boolean
+    element :include_pdf, Boolean
+    element :include_time_entries, Boolean
+    element :invoice_date, Date
+    element :item_actual, Float # readonly
+    element :item_cost, Float # readonly
+    element :item_profit, Float # readonly
+    element :item_taxable, Float # readonly
+    element :late_fee, Float # readonly
+    element :late_percentage, Float
+    element :late_period_in_days, Integer
+    element :notes
+    element :payment_total, Float # readonly
+    element :post_reminder_in_days, Integer
+    element :pre_reminder_in_days, Integer
+    element :sales_tax, Float
+    element :sales_tax_2, Float
+    element :sales_tax_2_cumulative, Boolean
+    element :total, Float # readonly
+    element :total_quantity, Float # readonly
+    
+    # Returns all associated LineItems
+    def line_items(options={})
+      self.class.get_collection(
+        self.links[:line_items], Cashboard::InvoiceLineItem, options
+      )
+    end
+    
+    # Imports uninvoiced items (time entries, expenses, flat fee tasks) 
+    # that belong to the same client that this invoice was created for.
+    #
+    # Either raises a Cashboard error (errors.rb) or returns a collection
+    # of Cashboard::InvoiceLineItem objects.
+    def import_uninvoiced_items(project_ids={}, start_date=nil, end_date=nil)
+      xml_options = get_import_xml_options(project_ids, start_date, end_date)
+      
+      options = self.class.merge_options()
+      options.merge!({:body => xml_options})
+      response = self.class.put(self.links[:import_uninvoiced_items], options)
+      
+      self.class.check_status_code(response)
+      
+      collection = response.parsed_response[Cashboard::InvoiceLineItem.resource_name.singularize]      
+      collection.map do |h| 
+        Cashboard::InvoiceLineItem.new(h)
+      end
+    end
+        
+    def get_import_xml_options(project_ids, start_date, end_date)
+      xml_options = ''
+      xml = Builder::XmlMarkup.new(:target => xml_options, :indent => 2)
+      xml.instruct!
+      xml.projects do
+        project_ids.each {|pid| xml.id pid} if project_ids
+      end
+      xml.start_date start_date
+      xml.end_date end_date
+      
+      return xml_options  
+    end
+  end
+end

data/lib/cashboard/invoice_line_item.rb

@@ -0,0 +1,15 @@
+module Cashboard
+  class InvoiceLineItem < Base
+    element :description
+    element :flat_fee, Float
+    element :invoice_id
+    element :invoice_schedule_id
+    element :is_taxable, Boolean
+    element :markup_percentage, Float
+    element :price_per, Float
+    element :quantity, Float
+    element :rank, Integer
+    element :title
+    element :total, Float # readonly
+  end
+end

data/lib/cashboard/invoice_payment.rb

@@ -0,0 +1,7 @@
+module Cashboard
+  class InvoicePayment < Base
+    element :invoice_id
+    element :payment_id
+    element :amount, Float
+  end
+end

data/lib/cashboard/line_item.rb

@@ -0,0 +1,27 @@
+module Cashboard
+  class LineItem < Base
+    TYPE_CODES = {
+      :custom => 0,
+      :task => 1,
+      :product => 2
+    }
+    
+    element :best_time_in_minutes, Integer
+    element :created_on, DateTime
+    element :description, String
+    element :estimate_id, String
+    element :flat_fee, Float
+    element :is_complete, Boolean
+    element :is_taxable, Boolean
+    element :markup_percentage, Float
+    element :price_per, Float
+    element :project_id, String
+    element :quantity_low, Float
+    element :quantity_high, Float
+    element :rank, Integer
+    element :title, String
+    element :type_code, Integer
+    element :unit_label, String
+    element :worst_time_in_minutes, Integer
+  end
+end

data/lib/cashboard/payment.rb

@@ -0,0 +1,22 @@
+module Cashboard
+  class Payment < Base
+    element :amount, Float
+    element :assigned_id
+    element :client_id
+    element :client_type
+    element :created_on, Date
+    element :document_template_id
+    element :estimate_id
+    element :notes
+    element :person_id
+    element :transaction_id
+    
+    # Returns all InvoicePayments associated with this payment
+    def invoice_payments(options={})
+      self.class.get_collection(
+        self.links[:invoices], Cashboard::InvoicePayment, options
+      )
+    end
+    
+  end
+end

data/lib/cashboard/project.rb

@@ -0,0 +1,38 @@
+module Cashboard
+  class Project < Base
+    include Cashboard::Behaviors::Toggleable
+    include Cashboard::Behaviors::ListsLineItems
+    
+    BILLING_CODES = {
+      :non_billable => 0,
+      :task_rate => 1,
+      :employee_rate => 2
+    }
+    
+    CLIENT_VIEW_TIME_CODES = {
+      :show_when_invoiced => 0,
+      :show_when_marked_billable => 1,
+      :never => 2
+    }
+    
+    element :billing_code, Integer
+    element :client_name, String
+    element :client_id, Integer
+    element :client_type, String
+    element :client_view_time_code, Integer
+    element :completion_date, Date
+    element :created_on, Date
+    element :is_active, Boolean
+    element :name, String
+    element :rate, Float
+    element :start_date, Date
+    
+    # Returns all employee ProjectAssignments
+    def employee_project_assignments(options={})
+      self.class.get_collection(
+        self.links[:assigned_employees], Cashboard::ProjectAssignment, options
+      )
+    end
+
+  end
+end

data/lib/cashboard/project_assignment.rb

@@ -0,0 +1,9 @@
+module Cashboard
+  class ProjectAssignment < Base
+    element :bill_rate, Float
+    element :has_access, Boolean
+    element :pay_rate, Float
+    element :person_id
+    element :project_id
+  end
+end

data/lib/cashboard/time_entry.rb

@@ -0,0 +1,45 @@
+module Cashboard
+  class TimeEntry < Base
+    element :created_on, DateTime
+    element :description
+    element :invoice_line_item_id # readonly
+    element :is_billable, Boolean
+    element :is_running, Boolean # readonly
+    element :line_item_id
+    element :minutes, Integer
+    element :minutes_with_timer, Integer # readonly
+    element :person_id
+    element :timer_started_at, DateTime # readonly
+    
+    # Starts or stops timer depending on its current state.
+    #
+    # Will return an object of Cashboard::Struct if another timer was stopped
+    # during this toggle operation.
+    #
+    # Will return nil if no timer was stopped.
+    def toggle_timer
+      options = self.class.merge_options()
+      options.merge!({:body => self.to_xml})
+      response = self.class.put(self.links[:toggle_timer], options)
+      
+      # Raise special errors if not a success
+      self.class.check_status_code(response)
+      
+      # Re-initialize ourselves with information from response
+      initialize(response.parsed_response)
+      
+      if self.stopped_timer
+        stopped_timer = Cashboard::Struct.new(self.stopped_timer)
+      end
+      
+      stopped_timer || nil
+    end
+    
+    # If a TimeEntry has no invoice_line_item_id set, then it 
+    # hasn't been included on an invoice.
+    def has_been_invoiced?
+      !self.invoice_line_item_id.blank?
+    end
+    
+  end
+end

data/lib/cashboard/version.rb

@@ -0,0 +1,3 @@
+module Cashboard
+  VERSION = "1.0.1".freeze
+end

data/lib/cashboard.rb

@@ -0,0 +1,75 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__))
+
+require 'typecasted_open_struct'
+require 'rubygems'
+require 'active_support'
+require 'httparty'
+require 'xmlsimple'
+require 'builder'
+
+module Cashboard
+  # When reading the parsed hashes generated from parser we ignore these pairs.
+  IGNORED_XML_KEYS = ['rel', 'read_only']
+  
+  class Struct < TypecastedOpenStruct
+    # Since we're dealing with initializing from hashes with 'content'
+    # keys we need to set properties based on those keys.
+    #
+    # Additionally, we do some magic to ignore attributes we don't care about.
+    #
+    # The basic concept is lifted from ostruct.rb
+    def initialize(hash={})
+      @table = {}
+      return unless hash
+      hash.each do |k,v|
+        # Remove keys that aren't useful for our purposes.
+        if v.class == Hash
+          Cashboard::IGNORED_XML_KEYS.each {|ignored| v.delete(ignored)}
+        end
+        # Access items based on the 'content' key inside the hash.
+        # Allows us to deal with all XML tags equally, even if the tags
+        # have attributes or not.
+        if v.class == Hash && v['content']
+          @table[k.to_sym] = v['content']
+        elsif v.class == Hash && v.empty?
+          @table[k.to_sym] = nil
+        else
+          @table[k.to_sym] = v
+        end
+        new_ostruct_member(k)
+      end
+    end
+  end
+end
+
+# Override HTTParty's XML parsing, which doesn't really work
+# well for the output we receive.
+class HTTParty::Parser
+  protected
+    def xml
+      XmlSimple.xml_in(
+        body, 
+        'KeepRoot' => false, 
+        # Force 'link' tags into an array always
+        'ForceArray' => %w(link),
+        # Force each item into a hash with a 'content' key for the tag value
+        # If we don't do this random tag attributes can screw us up.
+        'ForceContent' => true
+      )
+    end
+end
+
+# After we've defined some basics let's include 
+# the Cashboard-rb API libraries
+
+# Load base first or there's some issues with dependencies.
+require 'cashboard/base'
+require 'cashboard/behaviors/base'
+require 'cashboard/behaviors/toggleable'
+require 'cashboard/behaviors/lists_line_items'
+
+library_files = Dir[File.join(File.dirname(__FILE__), 'cashboard/*.rb')]
+library_files.each do |lib| 
+  next if lib.include?('cashboard/base.rb')
+  require lib
+end

data/lib/typecasted_open_struct.rb

@@ -0,0 +1,82 @@
+require 'ostruct'
+require 'date'
+require 'time'
+
+class Boolean; end
+
+# A class to provide a quick and dirty way to typecast attributes
+# that we specify, while silently setting the rest.
+#
+# Allows us to specify important attributes, but doesn't force us to
+# update schema in order to deal with unexpected new properties.
+#
+#
+# Example:
+# 
+#   class MyFoo < TypecastedOpenStruct
+#     element :true_false_thing, Boolean
+#     element :amount, Float
+#  end
+class TypecastedOpenStruct < OpenStruct
+  @@elements = {}
+  
+  def self.element(name, attr_type=String, options={})
+    element = Element.new(name, attr_type, options)
+    @@elements[name] = element
+    
+    # Define getter to attr_typecast proper value
+    define_method(element.method_name) do
+      self.class.attr_typecast(
+        @table[element.method_name.to_sym], 
+        @@elements[name].attr_type
+      )
+    end
+  end
+  
+  # Lifted from HappyMapper. Thanks! :)
+  def self.attr_typecast(value, attr_type)
+    return value if value.kind_of?(attr_type) || value.nil?
+    begin
+      if    attr_type == String    then value.to_s
+      elsif attr_type == Float     then value.to_f
+      elsif attr_type == Time      then Time.parse(value.to_s)
+      elsif attr_type == Date      then Date.parse(value.to_s)
+      elsif attr_type == DateTime  then DateTime.parse(value.to_s)
+      elsif attr_type == Boolean   then ['true', 't', '1'].include?(value.to_s.downcase)
+      elsif attr_type == Integer
+        # ganked from datamapper
+        value_to_i = value.to_i
+        if value_to_i == 0 && value != '0'
+          value_to_s = value.to_s
+          begin
+            Integer(value_to_s =~ /^(\d+)/ ? $1 : value_to_s)
+          rescue ArgumentError
+            nil
+          end
+        else
+          value_to_i
+        end
+      else
+        value
+      end
+    rescue
+      value
+    end
+  end
+  
+  class Element
+    attr_types = [String, Float, Time, Date, DateTime, Integer, Boolean]
+  
+    attr_accessor :name, :attr_type, :options, :namespace
+  
+    def initialize(name, attr_type=String, options={})
+      self.name = name.to_s
+      self.attr_type = attr_type
+      self.options = options
+    end
+    
+    def method_name
+      @method_name ||= name.tr('-', '_')
+    end    
+  end
+end