costagent 0.1.6 → 0.2.0

data/README.rdoc

@@ -12,6 +12,8 @@ This isn't meant to be an entire Ruby library for the FA API - this is simply su
 
 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).
 
+Version 0.2.0 introduces some breaking changes to the existing API - namely moving from structs to dedicated classes backed by hashes for the FreeAgent resources. It also introduces a couple of new methods, and the ability for a third party caching provider to be plugged in - but this now means that there is NO in memory caching of anything (such as projects) at all. In short, just using this library and not supplying even a basic cache provider will mean that every single request will result in an HTTP call. Some default caching providers coming soon.
+
 == SYNOPSIS:
 
 To initialize:
@@ -20,6 +22,12 @@ costagent = CostAgent.new subdomain, username, password
 
 (remember you need to enable API access from within your FreeAgent account)
 
+To set a caching provider to limit repeat lookups to FreeAgent:
+
+CostAgent.cache_provider = MyCacheProvider.new
+
+(see the tests for a reference in memory cache provider)
+
 To see all active projects:
 
 projects = costagent.projects
@@ -52,6 +60,10 @@ To return your FA user ID:
 
 costagent.user_id
 
+And to return all details about the logged in user:
+
+costagent.user
+
 To return a total of the amount of hours worked for a specific timeframe:
 
 hours = costagent.worked(start_date, end_date)

data/lib/costagent.rb

@@ -6,14 +6,53 @@ require "open-uri"
 
 #  This exposes additional billable tracking functionality around the Freeagent API
 class CostAgent
-  Project = Struct.new(:id, :name, :currency, :hourly_billing_rate, :daily_billing_rate, :hours_per_day)
-  Timeslip = Struct.new(:id, :project, :task, :hours, :date, :cost, :comment, :status)
-  Task = Struct.new(:id, :name, :project, :hourly_billing_rate, :daily_billing_rate, :billable)
-  Invoice = Struct.new(:id, :project_id, :description, :reference, :amount, :status, :date, :due, :items)
-  InvoiceItem = Struct.new(:id, :invoice_id, :project_id, :item_type, :description, :price, :quantity, :cost)
+  # This provides shared functionality for all of the wrapped FA data types
+  class Base
+    attr_accessor :data
 
+    def initialize(data = {})
+      @data = data
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s
+      if key[key.length - 1] == "="
+        @data[key[0...key.length - 1]] = args.first
+      end
+      @data[key] || @data[key.to_sym]
+    end
+  end
+
+  # Our FA data types
+  class Project < Base; end
+  class Timeslip < Base; end
+  class Task < Base; end
+  class Invoice < Base; end
+  class InvoiceItem < Base; end
+  class User < Base; end
+
+  # Our configuration for FA access
   attr_accessor :subdomain, :username, :password
   
+  # Our cache provider, to help to limit the amount of requests and lookups to FA
+  class << self
+    attr_accessor :cache_provider
+  end
+
+  # This calls out to the external third party provider for caching
+  def cache(resource, identifier, reload = false, &block)
+    if CostAgent.cache_provider.nil?
+      block.call
+    else
+      if (!reload && CostAgent.cache_provider.exists?(self.subdomain, resource, identifier))
+        CostAgent.cache_provider.get(self.subdomain, resource, identifier)
+      else
+        CostAgent.cache_provider.set(self.subdomain, resource, identifier, block.call)
+      end
+    end
+  end
+
+  # Initialize and validate input data
   def initialize(subdomain, username, password)
     self.subdomain = subdomain
     self.username = username
@@ -25,101 +64,117 @@ class CostAgent
   end
     
   # Returns all projects
-  def projects(filter = "active")
-    @projects ||= {}
-    @projects[filter] ||= (self.api("projects", {:view => filter})/"project").collect do |project|
-      billing_rate = (project/"normal-billing-rate").text.to_f
-      hours_per_day = (project/"hours-per-day").text.to_f
-      billing_period = (project/"billing-period").text
-      hourly_rate = (billing_period == "hour" ? billing_rate : billing_rate / hours_per_day)
-      daily_rate = (billing_period == "hour" ? billing_rate * hours_per_day : billing_rate)
-      Project.new((project/"id").text.to_i,
-                  (project/"name").text,
-                  (project/"currency").text,
-                  hourly_rate,
-                  daily_rate,
-                  hours_per_day)
+  def projects(filter = "active", reload = false)
+    self.cache(CostAgent::Project, filter, reload) do
+      (self.api("projects", {:view => filter})/"project").collect do |project|
+        billing_rate = (project/"normal-billing-rate").text.to_f
+        hours_per_day = (project/"hours-per-day").text.to_f
+        billing_period = (project/"billing-period").text
+        hourly_rate = (billing_period == "hour" ? billing_rate : billing_rate / hours_per_day)
+        daily_rate = (billing_period == "hour" ? billing_rate * hours_per_day : billing_rate)
+        Project.new(
+          :id => (project/"id").text.to_i,
+          :name => (project/"name").text,
+          :currency => (project/"currency").text,
+          :hourly_billing_rate => hourly_rate,
+          :daily_billing_rate => daily_rate,
+          :hours_per_day => hours_per_day)
+      end
     end
   end
-    
+
   # This returns the specified project
   def project(id)
     self.projects("all").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)
-      if project
-        task = self.tasks(project.id).detect { |t| t.id == (timeslip/"task-id").text.to_i }
-        hours = (timeslip/"hours").text.to_f
-        cost = (task.nil? ? project : task).hourly_billing_rate * hours
-        # Build the timeslip out using the timeslip data and the project it's tied to
-        Timeslip.new((timeslip/"id").text.to_i,
-                     project,
-                     task,
-                     hours,
-                     DateTime.parse((timeslip/"dated-on").text),
-                     cost,
-                     (timeslip/"comment").text,
-                     (timeslip/"status").text)
-      else
-        nil
-      end
-    end - [nil]
+  def timeslips(start_date = DateTime.now, end_date = start_date, reload = false)
+    self.cache(CostAgent::Timeslip, "#{start_date.strftime("%Y-%m-%d")}_#{end_date.strftime("%Y-%m-%d")}", reload) do
+      timeslips = (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)
+        if project
+          task = self.tasks(project.id).detect { |t| t.id == (timeslip/"task-id").text.to_i }
+          hours = (timeslip/"hours").text.to_f
+          cost = (task.nil? ? project : task).hourly_billing_rate * hours
+          # Build the timeslip out using the timeslip data and the project it's tied to
+          Timeslip.new(
+            :id => (timeslip/"id").text.to_i,
+            :project_id => project.id,
+            :project => project,
+            :task_id => task.id,
+            :task => task,
+            :hours => hours,
+            :date => DateTime.parse((timeslip/"dated-on").text),
+            :cost => cost,
+            :comment => (timeslip/"comment").text,
+            :status => (timeslip/"status").text)
+        else
+          nil
+        end
+      end - [nil]
+    end
   end
 
   # This returns all tasks for the specified project_id
-  def tasks(project_id)
-    (self.api("projects/#{project_id}/tasks")/"task").collect do |task|
-      # Find the project for this task
-      project = self.project((task/"project-id").text.to_i)
-      # Calculate rates
-      billing_rate = (task/"billing-rate").text.to_f
-      billing_period = (task/"billing-period").text
-      hourly_rate = (billing_period == "hour" ? billing_rate : billing_rate / project.hours_per_day)
-      daily_rate = (billing_period == "hour" ? billing_rate * project.hours_per_day : billing_rate)
-      # Build the task out using the task data and the project it's tied to
-      Task.new((task/"id").text.to_i,
-                   (task/"name").text,
-                   project,
-                   hourly_rate,
-                   daily_rate,
-                   (task/"is-billable").text == "true")
+  def tasks(project_id, reload = false)
+    self.cache(CostAgent::Task, project_id, reload) do
+      (self.api("projects/#{project_id}/tasks")/"task").collect do |task|
+        # Find the project for this task
+        project = self.project((task/"project-id").text.to_i)
+        # Calculate rates
+        billing_rate = (task/"billing-rate").text.to_f
+        billing_period = (task/"billing-period").text
+        hourly_rate = (billing_period == "hour" ? billing_rate : billing_rate / project.hours_per_day)
+        daily_rate = (billing_period == "hour" ? billing_rate * project.hours_per_day : billing_rate)
+        # Build the task out using the task data and the project it's tied to
+        Task.new(
+          :id => (task/"id").text.to_i,
+          :name => (task/"name").text,
+          :project_id => project.id,
+          :project => project,
+          :hourly_billing_rate => hourly_rate,
+          :daily_billing_rate => daily_rate,
+          :billable => (task/"is-billable").text == "true")
+      end
     end
   end
 
   # This returns all invoices
-  def invoices
-    @invoices ||= (self.api("invoices")/"invoice").collect do |invoice|
-      items = (invoice/"invoice-item").collect do |item|
-        price = (item/"price").first.inner_text.to_f
-        quantity = (item/"quantity").first.inner_text.to_f
-        cost = price * quantity
-        InvoiceItem.new(
-          (item/"id").first.inner_text.to_i,
-          (item/"invoice-id").first.inner_text.to_i,
-          (item/"project-id").first.inner_text.to_i,
-          (item/"item-type").first.inner_text,
-          (item/"description").first.inner_text,
-          price,
-          quantity,
-          cost)
+  def invoices(reload = false)
+    self.cache(CostAgent::Invoice, :all, reload) do
+      (self.api("invoices")/"invoice").collect do |invoice|
+        items = (invoice/"invoice-item").collect do |item|
+          price = (item/"price").first.inner_text.to_f
+          quantity = (item/"quantity").first.inner_text.to_f
+          cost = price * quantity
+          project = self.project((item/"project-id").first.inner_text.to_i)
+          InvoiceItem.new(
+            :id => (item/"id").first.inner_text.to_i,
+            :invoice_id => (item/"invoice-id").first.inner_text.to_i,
+            :project_id => project.id,
+            :project => project,
+            :item_type => (item/"item-type").first.inner_text,
+            :description => (item/"description").first.inner_text,
+            :price => price,
+            :quantity => quantity,
+            :cost => cost)
+        end
+        project = self.project((invoice/"project-id").first.inner_text.to_i)
+        Invoice.new(
+          :id => (invoice/"id").first.inner_text.to_i,
+          :project_id => project.id,
+          :project => project,
+          :description => (invoice/"description").first.inner_text,
+          :reference => (invoice/"reference").text,
+          :amount => (invoice/"net-value").text.to_f,
+          :status => (invoice/"status").text,
+          :date => DateTime.parse((invoice/"dated-on").text),
+          :due => DateTime.parse((invoice/"due-on").text),
+          :items => items)
       end
-      Invoice.new(
-        (invoice/"id").first.inner_text.to_i,
-        (invoice/"project-id").first.inner_text.to_i,
-        (invoice/"description").first.inner_text,
-        (invoice/"reference").text,
-        (invoice/"net-value").text.to_f,
-        (invoice/"status").text,
-        DateTime.parse((invoice/"dated-on").text),
-        DateTime.parse((invoice/"due-on").text),
-        items)
     end
-    @invoices
   end
 
   # This returns the specific invoice by ID
@@ -127,9 +182,20 @@ class CostAgent
     self.invoices.detect { |i| i.id == id }
   end
 
+  # This contains the logged in user information for the configured credentials
+  def user(reload = false)
+    self.cache(CostAgent::User, self.username, reload) do
+      data = self.client("verify").get.headers
+      [User.new(
+        :id => data[:user_id],
+        :permissions => data[:user_permission_level],
+        :company_type => data[:company_type])]
+    end.first
+  end
+
   # This looks up the user ID using the CostAgent credentials
   def user_id
-    self.client("verify").get.headers[:user_id]
+    self.user.id
   end
 
   # This returns the amount of hours worked

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 6
-  version: 0.1.6
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Elliott Draper
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-11 00:00:00 +01:00
+date: 2010-10-13 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency