cashboard 1.0.1

data/.autotest

@@ -0,0 +1,26 @@
+require 'redgreen/autotest'
+
+Autotest.add_hook :initialize do |at|
+  # Ignore these files
+  %w{
+    .hg .git .svn stories tmtags Rakefile Capfile README .html
+    spec/spec.opts spec/rcov.opts vendor/gems autotest svn-commit .DS_Store
+  }.each {|exception|at.add_exception(exception)}
+
+  at.clear_mappings
+
+  # Test everything in cashboard/lib
+  at.add_mapping(%r%^lib/cashboard/(.*)\.rb$%) do |file, m|
+    # also run original class file
+    full_dir = File.dirname(file)
+    orig = full_dir[full_dir.rindex('/')+1, full_dir.length]
+    model = File.basename(file, '.rb')
+
+    at.files_matching %r%^test/unit/#{model}_test\.rb$%
+  end
+  
+  # Now add support for the test files themselves
+  at.add_mapping(%r%^test/unit/(.*)\.rb$%) do |file, m|
+    at.files_matching %r%#{file}%
+  end
+end

data/.gitignore

@@ -0,0 +1,2 @@
+# Ignore built gems from jeweler
+pkg

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Subimage LLC
+
+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.
+
+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.textile

@@ -0,0 +1,58 @@
+h1. Cashboard-rb
+
+This project is the official Ruby wrapper for the "Cashboard API":http://api.cashboardapp.com created and maintained by "Subimage LLC":http://www.subimage.com.
+
+"Cashboard":http://www.getcashboard.com is an online service that allows you to track time, create estimates, invoice your clients, and collect payments via credit cards or PayPal.
+
+
+h2. Installation
+
+bc. sudo gem install cashboard
+
+
+h2. Example Code
+
+bc.. require 'rubygems'
+require 'cashboard'
+
+Cashboard::Base.authenticate('your_subdomain', 'your_api_key')
+
+puts "Employees:"
+Cashboard::Employee.list.each { |emp| puts emp.inspect }
+
+puts "Client Companies:"
+Cashboard::ClientCompany.list.each { |client| puts client.inspect }
+
+puts "Projects:"
+Cashboard::Project.list.each { |prj| puts prj.inspect }
+
+p. There are more examples in the /examples directory of this project.
+
+
+h2. Links
+
+* "Cashboard API Documentation":http://api.cashboardapp.com
+* "Cashboard API Forum":http://forum.getcashboard.com/forums/7
+* "Source code for Cashboard-rb":http://github.com/subimage/cashboard-rb
+
+
+h2. Contributing
+
+If you'd like to contribute to this project, please fork it and add your code *with working tests*.
+
+
+h3. Testing
+
+Tests are handled with Test::Unit and Fakeweb.
+There's a complete test suite you can run by invoking:
+@ruby test/full.rb@
+
+The project is also setup to use autotest.
+
+If you add any code please ensure all tests continue to run properly by running the test suite.
+
+
+h2. License
+
+Cashboard-rb is released under the MIT License.
+Tweak it, fork it, twerk it and translate it to other languages...please!

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'rake'
+
+require File.dirname(__FILE__) + "/lib/cashboard"
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "cashboard"
+    gem.summary = "Ruby wrapper library for the Cashboard API "
+    gem.description = "For more information see the homepage. Support and discussion can be found on the Cashboard forum (http://forum.getcashboard.com/)"
+    gem.email = "support@getcashboard.com"
+    gem.homepage = "http://github.com/subimage/cashboard-rb"
+    gem.authors = ["Subimage LLC"]
+    gem.version = Cashboard::VERSION
+    gem.add_development_dependency('mocha', '>= 0.9.8')
+    gem.add_development_dependency('fakeweb', '>= 1.2.8')
+    gem.add_dependency('activesupport', '>= 2.3.5')
+    gem.add_dependency('httparty', '>= 0.6.1')
+    gem.add_dependency('xml-simple', '>= 1.0.12')
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/cashboard.gemspec

@@ -0,0 +1,129 @@
+# 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{cashboard}
+  s.version = "1.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Subimage LLC"]
+  s.date = %q{2010-07-29}
+  s.description = %q{For more information see the homepage. Support and discussion can be found on the Cashboard forum (http://forum.getcashboard.com/)}
+  s.email = %q{support@getcashboard.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile"
+  ]
+  s.files = [
+    ".autotest",
+     ".gitignore",
+     "LICENSE",
+     "README.textile",
+     "Rakefile",
+     "cashboard.gemspec",
+     "examples/create_account.rb",
+     "examples/list_stuff_in_account.rb",
+     "examples/simple_workflow.rb",
+     "examples/time_tracking.rb",
+     "examples/toggle_timer.rb",
+     "lib/cashboard.rb",
+     "lib/cashboard/account.rb",
+     "lib/cashboard/base.rb",
+     "lib/cashboard/behaviors/base.rb",
+     "lib/cashboard/behaviors/lists_line_items.rb",
+     "lib/cashboard/behaviors/toggleable.rb",
+     "lib/cashboard/client_company.rb",
+     "lib/cashboard/client_contact.rb",
+     "lib/cashboard/company_membership.rb",
+     "lib/cashboard/document_template.rb",
+     "lib/cashboard/employee.rb",
+     "lib/cashboard/errors.rb",
+     "lib/cashboard/estimate.rb",
+     "lib/cashboard/expense.rb",
+     "lib/cashboard/invoice.rb",
+     "lib/cashboard/invoice_line_item.rb",
+     "lib/cashboard/invoice_payment.rb",
+     "lib/cashboard/line_item.rb",
+     "lib/cashboard/payment.rb",
+     "lib/cashboard/project.rb",
+     "lib/cashboard/project_assignment.rb",
+     "lib/cashboard/time_entry.rb",
+     "lib/cashboard/version.rb",
+     "lib/typecasted_open_struct.rb",
+     "test/fixtures/account.xml",
+     "test/fixtures/cashboard_credentials.yml",
+     "test/fixtures/client_companies.xml",
+     "test/fixtures/client_contacts.xml",
+     "test/fixtures/company_memberships.xml",
+     "test/fixtures/document_templates.xml",
+     "test/fixtures/employees.xml",
+     "test/fixtures/estimates.xml",
+     "test/fixtures/expenses.xml",
+     "test/fixtures/invoice_line_items.xml",
+     "test/fixtures/invoice_payments.xml",
+     "test/fixtures/invoices.xml",
+     "test/fixtures/line_items.xml",
+     "test/fixtures/payments.xml",
+     "test/fixtures/project_assignments.xml",
+     "test/fixtures/projects.xml",
+     "test/fixtures/time_entries.xml",
+     "test/full.rb",
+     "test/test_helper.rb",
+     "test/unit/account_test.rb",
+     "test/unit/document_template_test.rb",
+     "test/unit/estimate_test.rb",
+     "test/unit/expense_test.rb",
+     "test/unit/invoice_test.rb",
+     "test/unit/project_test.rb",
+     "test/unit/time_entry_test.rb"
+  ]
+  s.homepage = %q{http://github.com/subimage/cashboard-rb}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Ruby wrapper library for the Cashboard API}
+  s.test_files = [
+    "test/full.rb",
+     "test/test_helper.rb",
+     "test/unit/account_test.rb",
+     "test/unit/document_template_test.rb",
+     "test/unit/estimate_test.rb",
+     "test/unit/expense_test.rb",
+     "test/unit/invoice_test.rb",
+     "test/unit/project_test.rb",
+     "test/unit/time_entry_test.rb",
+     "examples/create_account.rb",
+     "examples/list_stuff_in_account.rb",
+     "examples/simple_workflow.rb",
+     "examples/time_tracking.rb",
+     "examples/toggle_timer.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<mocha>, [">= 0.9.8"])
+      s.add_development_dependency(%q<fakeweb>, [">= 1.2.8"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.3.5"])
+      s.add_runtime_dependency(%q<httparty>, [">= 0.6.1"])
+      s.add_runtime_dependency(%q<xml-simple>, [">= 1.0.12"])
+    else
+      s.add_dependency(%q<mocha>, [">= 0.9.8"])
+      s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
+      s.add_dependency(%q<activesupport>, [">= 2.3.5"])
+      s.add_dependency(%q<httparty>, [">= 0.6.1"])
+      s.add_dependency(%q<xml-simple>, [">= 1.0.12"])
+    end
+  else
+    s.add_dependency(%q<mocha>, [">= 0.9.8"])
+    s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
+    s.add_dependency(%q<activesupport>, [">= 2.3.5"])
+    s.add_dependency(%q<httparty>, [">= 0.6.1"])
+    s.add_dependency(%q<xml-simple>, [">= 1.0.12"])
+  end
+end
+

data/examples/create_account.rb

@@ -0,0 +1,38 @@
+# Shows a simple method to create an account via API
+# then connect and list resources for that account.
+
+require "../lib/cashboard"
+
+# Create a new account from the API
+# Creating an account doesn't require an authorized connection.
+begin
+  acct = Cashboard::Account.create({
+    :subdomain => 'WuTang',
+    :currency_type => 'USD',
+    :date_format => 'mm_dd_yyyy',
+    :owner => {
+      :email_address => 'rza@wutang.com',
+      :first_name => 'The',
+      :last_name => 'Rza',
+      :password => '36chambers'
+    },
+    :company => {
+      :name => 'Wu Tang',
+      :address => '1 Shogun Way',
+      :city => 'Shaolin',
+      :state => 'NY'
+    }
+  })
+rescue Cashboard::BadRequest => e
+  puts "Account creation failure"
+  puts e.errors.inspect
+end
+
+puts acct.inspect
+
+# Connect to account after we've created it
+Cashboard::Base.authenticate(acct.subdomain, acct.owner[:api_key])
+
+# List all projects in the account (should be 1 by default)
+puts "Projects:"
+Cashboard::Project.list.each {|prj| puts prj.inspect }

data/examples/list_stuff_in_account.rb

@@ -0,0 +1,15 @@
+# List various resources inside a Cashboard account
+# and display them on the screen.
+
+require "../lib/cashboard"
+
+Cashboard::Base.authenticate('your_subdomain', 'your_api_key')
+
+puts "Employees:"
+Cashboard::Employee.list.each { |emp| puts emp.inspect }
+
+puts "Client Companies:"
+Cashboard::ClientCompany.list.each { |client| puts client.inspect }
+
+puts "Projects:"
+Cashboard::Project.list.each { |prj| puts prj.inspect }

data/examples/simple_workflow.rb

@@ -0,0 +1,35 @@
+# Simple workflow that:
+# * Creates a client company
+# * Creates a project for that client
+# * Creates a task for the project
+# * Logs some time
+
+require "../lib/cashboard"
+
+Cashboard::Base.authenticate('your_subdomain', 'your_api_key')
+
+# Create a new client
+client = Cashboard::ClientCompany.create(
+  :name => 'Bigtime Ventures'
+)
+
+# Create a new project for that client
+project = Cashboard::Project.create(
+  :name => 'Bigtime Web Redesign', 
+  :client_id => client[:id],
+  :client_type => 'Company'
+)
+
+# Create task for project
+task = Cashboard::LineItem.create(
+  :project_id => project[:id],
+  :title => 'Graphic design'
+)
+
+# Track some time
+time_entry = Cashboard::TimeEntry.create(
+  :created_on => "04/11/2010", 
+  :minutes => 8*60,
+  :description => 'Trolled 4chan', 
+  :task_id => task[:id]
+)

data/examples/time_tracking.rb

@@ -0,0 +1,30 @@
+require "../lib/cashboard"
+
+Cashboard::Base.authenticate('your_subdomain', 'your_api_key')
+
+# Grab reference to first task in account
+prj = Cashboard::Project.list[0]
+
+# Grab reference to first task
+task = prj.tasks[0]
+
+puts "Creating a time entry for..."
+puts "  Project: #{prj.name}"
+puts "  Task   : #{task.title}\n\n"
+
+# Create a time entry for it
+te = Cashboard::TimeEntry.create({
+  :line_item_id => task.id,
+  :minutes => 60,
+  :description => "Doin work!"
+})
+
+# Show our handy work
+puts te.inspect
+
+# Remove it
+if te.delete == true
+  puts "\nTime entry has been destroyed"
+else
+  puts "\nTime entry could not be destroyed"
+end

data/lib/cashboard/account.rb

@@ -0,0 +1,21 @@
+module Cashboard
+  class Account < Base    
+    # Account is the only singular resource for the Cashboard API.
+    def self.resource_name; 'account'; end
+    
+    # We get some sub-resources that we need to turn into
+    # Cashboard::Structs so we can access their information
+    # in a friendly way.
+    def initialize(hash={})
+      super hash
+      self.owner = Cashboard::Struct.new(self.owner)
+      self.company = Cashboard::Struct.new(self.company)
+      self
+    end
+    
+    def href
+      "/#{self.class.resource_name}"
+    end
+    
+  end
+end

data/lib/cashboard/base.rb

@@ -0,0 +1,223 @@
+module Cashboard
+  class Base < Cashboard::Struct
+    include HTTParty
+    
+    if defined? TEST_ENVIRONMENT
+      @@api_url = "http://apicashboard.i" 
+    else
+      @@api_url = "https://api.cashboardapp.com" 
+    end
+    
+    base_uri @@api_url
+    
+    cattr_accessor :auth
+    cattr_accessor :api_url
+    
+    # Stores id and url for resource when instantiated
+    attr_accessor :id
+    attr_accessor :href
+      
+    # Sets authentication credentials for all following requests.
+    def self.authenticate(subdomain, api_key)
+      @@auth = {:username => subdomain, :password => api_key}
+    end
+    
+    # Clears authentication credentials.
+    def self.clear_authentication
+      @@auth = {}
+    end
+    
+    # Initializes an object of this type by passing a known URL in.
+    def self.new_from_url(url, options={})
+      response = get(url, merge_options(options))
+      check_status_code(response)
+      return self.new(response[resource_name])        
+    end
+    
+    # Lists all items for a resource.
+    #
+    # Returns array of objects of the type listed.
+    # raises error if something goes wrong.
+    def self.list(options={})
+      self.get_collection("/#{resource_name}", self, options)
+    end
+    
+    # Creates a resource.
+    #
+    # Returns object of type created if success, or raise error
+    # if something went wrong.
+    #
+    # Allows you to pass in a hash to create without naming it.
+    #
+    # Example:
+    #
+    # te = Cashboard::TimeEntry.create({
+    #   :minutes => 60, :project_id => 12345
+    # })
+    def self.create(params={}, options={})
+      options = merge_options(options)
+      options.merge!({:body => self.new(params).to_xml})
+      response = post("/#{resource_name}", options)
+      check_status_code(response)
+      return self.new(response.parsed_response)
+    end
+    
+    # INSTANCE METHODS ========================================================
+        
+    # Override OpenStruct's implementation of the id property.
+    # This allows us to set and retrieve id's for our corresponding
+    # Cashboard items.
+    def id; @table[:id]; end
+    
+    # Returns hash of HTTP links for this object, returned as <link>
+    # tags in the XML.
+    #
+    # These links determine what you can do with an object, as defined
+    # by the Cashboard API.
+    def links
+      @links ||= begin
+        links = HashWithIndifferentAccess.new
+        self.link.each do |link|
+          links[link['rel']] = link['href']
+        end
+        links
+      end
+    end
+    
+    # The unique HTTP URL that is used to access an object.
+    def href; self.links[:self]; end
+
+    # Updates the object on server, after attributes have been set.
+    # Returns boolean if successful
+    #
+    # Example:
+    #   te = Cashboard::TimeEntry.new_from_url(time_entry_url)
+    #   te.minutes = 60
+    #   update_success = te.update
+    def update
+      options = self.class.merge_options()
+      options.merge!({:body => self.to_xml})
+      response = self.class.put(self.href, options)
+      begin 
+        self.class.check_status_code(response)
+      rescue
+        return false
+      end
+      return true
+    end
+  
+    # Destroys Cashboard object on the server.
+    # Returns boolean upon success.
+    def delete
+      options = self.class.merge_options()
+      response = self.class.delete(self.href, options)
+      begin 
+        self.class.check_status_code(response)
+      rescue
+        return false
+      end
+      return true
+    end
+    
+    # Utilizes ActiveSupport to turn our objects into XML
+    # that we can pass back to the server.
+    #
+    # General concept stolen from Rails CoreExtensions::Hash::Conversions
+    def to_xml(options={})
+      options[:indent] ||= 2
+      xml = options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
+      xml.instruct! unless options[:skip_instruct]
+
+      obj_name = self.class.resource_name.singularize
+      
+      # Turn our OpenStruct attributes into a hash we can export to XML
+      obj_attrs = self.marshal_dump
+      
+      xml.tag!(obj_name) do
+        obj_attrs.each do |key,value|
+          next if key.to_sym == :link # Don't feed back links to server
+          case value
+            when ::Hash
+              value.to_xml(
+                options.merge({ 
+                  :root => key, 
+                  :skip_instruct => true 
+                })
+              )
+            when ::Array
+              value.to_xml(
+                options.merge({ 
+                  :root => key, 
+                  :children => key.to_s.singularize, 
+                  :skip_instruct => true
+                })
+              )
+            else
+              xml.tag!(key, value)
+          end
+        end
+      end
+    end
+    
+    protected
+      # No-configuration way to grab the resource name we're operatingo on.
+      # As long as we stick to a proper naming convention we have 
+      # less shit to type out.
+      def self.resource_name
+        name.demodulize.tableize
+      end
+   
+      # Lists a collection of things from the API and returns as
+      # an array of 'klass_to_return' items.
+      def self.get_collection(url, klass_to_return, options={})
+        response = get(url, merge_options(options))
+        check_status_code(response)
+        collection = response.parsed_response[klass_to_return.resource_name.singularize]
+        collection.map do |h| 
+          klass_to_return.new(h)
+        end
+      end
+    
+      # Ensures authentication and headers are set as options 
+      # on each request.
+      def self.merge_options(options={})
+        options.merge!(
+          {
+            :basic_auth => @@auth, 
+            :format => :xml,
+            :headers => {
+              'content-type' => 'application/xml'
+            }
+          }
+        )
+      end
+      
+      # Checks http status code and raises exception if it's not in 
+      # the realm of acceptable statuses.
+      def self.check_status_code(response)
+        case response.code
+          when 200, 201
+            return # Good status codes
+          when 400
+            raise Cashboard::BadRequest.new(response)
+          when 401
+            raise Cashboard::Unauthorized.new(response)
+          when 402
+            raise Cashboard::PaymentRequired.new(response)
+          when 403
+            raise Cashboard::Forbidden.new(response)
+          when 404
+            raise Cashboard::NotFound.new(response)
+          when 500
+            raise Cashboard::ServerError.new(response)
+          when 502
+            raise Cashboard::Unavailable.new(response)
+          when 503
+            raise Cashboard::RateLimited.new(response)
+          else
+            raise Cashboard::HTTPError.new(response)
+        end
+      end
+  
+  end # Cashboard::Base
+end

data/lib/cashboard/behaviors/base.rb

@@ -0,0 +1,4 @@
+module Cashboard
+  module Behaviors
+  end
+end

data/lib/cashboard/behaviors/lists_line_items.rb

@@ -0,0 +1,32 @@
+# Standard interface to list associated LineItems
+# for Projects and Estimates
+module Cashboard::Behaviors::ListsLineItems
+  # Returns all associated LineItems regardless of type
+  def line_items(options={})
+    self.class.get_collection(
+      self.links[:line_items], Cashboard::LineItem, options
+    )
+  end
+
+  # LineItems of type 'task'
+  def tasks
+    self.filter_line_items_by :task
+  end
+
+  # LineItems of type 'product'
+  def products
+    self.filter_line_items_by :product
+  end
+
+  # LineItems of type 'custom'
+  def custom_items
+    self.filter_line_items_by :custom
+  end
+  
+  protected
+    def filter_line_items_by(type)
+      self.line_items.reject do |li| 
+        li.type_code != Cashboard::LineItem::TYPE_CODES[type]
+      end
+    end
+end