costagent 0.1.0

data/README.rdoc

@@ -0,0 +1,77 @@
+= costagent
+
+* http://github.com/ejdraper/costagent
+
+== DESCRIPTION:
+
+costagent is a Ruby gem that provides lightweight access to the projects/timeslips part of the FreeAgent API, with a view to tracking billable hours and figures.
+
+== FEATURES/PROBLEMS:
+
+This isn't meant to be an entire Ruby library for the FA API - this is simply supposed to be a simple to use read-only view of timeslip data for keeping track of billable hours and calculating money earnt.
+
+This assumes that when calculating money earnt, you want it in GBP, and it only copes with calculating timeslips either in GBP, or in USD (which is converted using xe.com where possible).
+
+== SYNOPSIS:
+
+To initialize:
+
+costagent = CostAgent.new subdomain, username, password
+
+(remember you need to enable API access from within your FreeAgent account)
+
+To see all projects:
+
+projects = costagent.projects
+
+To find a specific project:
+
+project = costagent.project(id)
+
+To find timeslips:
+
+timeslips = costagent.timeslips(start_date, end_date)
+
+And to return a GBP figure of the money earnt during a specific timeframe based on billable hours:
+
+total = costagent.earnt(start_date, end_date)
+
+You can see the USD rate used for conversion:
+
+CostAgent.usd_rate
+
+This returns 1.6 if there is any error reaching or parsing xe.com. It's also stored once retrieved in a class variable so it doesn't keep querying everytime it's needed.
+
+== REQUIREMENTS:
+
+rest-client (1.5.0)
+hpricot (0.8.2)
+
+== INSTALL:
+
+gem install costagent
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Elliott Draper <el@ejdraper.com>
+
+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/lib/costagent.rb

@@ -0,0 +1,74 @@
+require "rubygems"
+require "date"
+gem "rest-client"; require "rest_client"
+gem "hpricot"; require "hpricot"
+require "open-uri"
+
+#  This exposes additional billable tracking functionality around the Freeagent API
+class CostAgent
+  Project = Struct.new(:id, :name, :currency, :hourly_billing_rate)
+  Timeslip = Struct.new(:id, :project, :hours, :date, :cost)
+
+  attr_accessor :subdomain, :username, :password
+  
+  def initialize(subdomain, username, password)
+    self.subdomain = subdomain
+    self.username = username
+    self.password = password
+
+    [:subdomain, :username, :password].each do |f|
+      raise "No #{f} configured!" if self.send(f).nil? || self.send(f).empty?
+    end
+  end
+    
+  # Returns all projects
+  def projects
+    @projects ||= (self.api("projects")/"project").collect { |project| Project.new((project/"id").text.to_i, (project/"name").text, (project/"currency").text, (project/"normal-billing-rate").text.to_f) }
+  end
+    
+  # This returns the specified project
+  def project(id)
+    self.projects.detect { |p| p.id == id }
+  end
+
+  # This returns all timeslips for the specified date range, with additional cost information
+  def timeslips(start_date = DateTime.now, end_date = start_date)
+    (self.api("timeslips", :view => "#{start_date.strftime("%Y-%m-%d")}_#{end_date.strftime("%Y-%m-%d")}")/"timeslip").collect do |timeslip|
+      # Find the project and hours for this timeslip
+      project = self.project((timeslip/"project-id").text.to_i)
+      hours = (timeslip/"hours").text.to_f
+      # Build the timeslip out using the timeslip data and the project it's tied to
+      Timeslip.new((timeslip/"id").text.to_i,
+                   project,
+                   hours,
+                   DateTime.parse((timeslip/"updated-at").text),
+                   project.hourly_billing_rate * hours)
+    end
+  end
+    
+  # This returns the amount of GBP earnt in the specified timeframe
+  def earnt(start_date = DateTime.now, end_date = start_date)
+    self.timeslips(start_date, end_date).collect do |timeslip|
+      if timeslip.project.currency == "GBP"
+        timeslip.cost
+      else
+        timeslip.cost / CostAgent.usd_rate
+      end
+    end.inject(0) { |sum, i| sum += i }
+  end
+    
+  # This calls the FA API for the specified resource
+  def api(resource, parameters = {})
+    url = "https://#{self.subdomain}.freeagentcentral.com/#{resource}#{parameters.empty? ? "" : "?" + parameters.collect { |p| p.join("=") }.join("&")}"
+    res = RestClient::Resource.new(url, self.username, self.password).get
+    raise "No response from #{url}!" if res.body.nil? && res.body.empty?
+    Hpricot(res.body)
+  end
+
+  class << self
+    # This returns the current USD rate from xe.com (or falls back on 1.6 if there is an error)
+    def usd_rate
+      @@rate ||= ((Hpricot(Kernel.open("http://www.xe.com"))/"a").detect { |a| a.attributes["id"] == "USDGBP31" }.children.first.to_s.to_f rescue 1.6)
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: costagent
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Elliott Draper
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-11 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 5
+        - 0
+        version: 1.5.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 8
+        - 2
+        version: 0.8.2
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: 
+email: el@ejdraper.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- lib/costagent.rb
+has_rdoc: true
+homepage: http://github.com/ejdraper/costagent
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: costagent is a Ruby gem that provides lightweight access to the projects/timeslips part of the FreeAgent API, with a view to tracking billable hours and figures.
+test_files: []
+