freeagent_api 0.1.0 → 0.2.0

data/.gitignore

@@ -2,4 +2,4 @@
 .DS_Store
 coverage
 rdoc
-pkg
+pkg

data/README.rdoc

@@ -1,17 +1,24 @@
 = freeagent_api
 
-Simple Ruby interface to the Freeagent Central API (http://www.freeagentcentral.com/developers/freeagent-api).
+Simple ActiveResource Ruby wrapper for the Freeagent Central API (http://www.freeagentcentral.com/developers/freeagent-api).
 
-This is an early development version of a Ruby wrapper for the Freeagent API. Currently this only supports GET requests (POST will follow shortly) and only the following API methods are supported (more will follow):
+This supports all GET, POST, PUT and DELETE ActiveResource calls for the following API resources:
 
+* Company
 * Contacts
-* Invoices
-* Invoice items
 * Projects
 * Tasks
+* Invoices
+* Invoice Items
 * Timeslips
 
-There is no test suite yet. If you feel brave, then feel free to clone, fork and play around.
+At the moment, the following API resources are NOT supported (although is being worked on):
+
+* Users
+* Expenses
+* Attachments
+
+Feel free to clone, fork and add tests.
 
 == Installation
 
@@ -19,43 +26,208 @@ To install as a Gem, just run:
 
   $ sudo gem install freeagent_api -s http://gemcutter.org
 
+Please note: version 0.2 is significantly different from 0.1 so if you are upgrading from the early development version please re-familiarise yourself with the documentation.
+
 == Usage
 
 === Authentication
 
-  Freeagent.domain = 'yourdomain.freeagentcentral.com'
-  Freeagent.username = 'your@login.com'
-  Freeagent.password = 'your_password'
+  Freeagent.authenticate({
+    :domain => 'yourdomain.freeagentcentral.com',
+    :username => 'your@login.com',
+    :password => 'your_password'})
+
+=== Company
+
+<b>Timelines</b>
+
+  @invoice_timeline = Company.invoice_timeline
+  @tax_timeline = Company.tax_timeline
 
 === Contacts
 
-  @contacts = Contact.find_all                # returns all contacts
-  @contact = Contact.find(contact_id)         # returns specific contact
+<b>Find contacts</b>
 
-=== Invoice
+  @contacts = Contact.find :all         # returns all contacts
+  @contact = Contact.find id            # returns specific contact
 
-  @invoices = Invoice.find_all                # returns all invoices
-  @invoices = Invoice.find_all(project_id)    # returns all invoices for project
-  @invoice = Invoice.find(invoice_id)         # returns specific invoice
+<b>Create contact</b>
 
-=== Invoice items
+  # Required attributes
+  #   :first_name
+  #   :last_name
+  
+  @contact = Contact.new params
+  @contact.save
+
+<b>Update contact</b>
+
+  @contact.first_name = 'Joe'
+  @contact.save
 
-  @items  = InvoiceItem.find_all(invoice_id)  # returns all items for invoice
+<b>Delete contact</b>
+
+  Contact.delete id
+  # or
+  @contact.destroy
 
 === Projects
 
-  @projects = Project.find_all                # returns all projects
-  @project = Project.find(project_id)         # returns specific project
+<b>Find projects</b>
+
+  @projects = Project.find :all         # returns all projects
+  @project = Project.find id            # returns specific project
+
+<b>Create project</b>
+
+  # Required attribues
+  #   :contact_id
+  #   :name
+  #   :payment_term_in_days
+  #   :billing_basis                    # must be 1, 7, 7.5, or 8
+  #   :budget_units                     # must be Hours, Days, or Monetary
+  #   :status                           # must be Active or Completed
+  
+  @project = Project.new params
+  @project.save
+
+<b>Update project</b>
+
+  @project.name = 'Web design project'
+  @project.save
+
+<b>Delete project</b>
+
+  Project.delete id
+  # or
+  @project.destroy
+
+<b>Nested resources</b>
+
+  @invoices = @project.invoices
+  @timeslips = @project.timeslips
 
 === Tasks
 
-  @task = Task.find(project_id, task_id)      # returns specific task for project
+<b>Find tasks</b>
+
+  @tasks = Task.find :all               # returns all tasks
+  @task = Task.find id                  # returns specific task
+
+<b>Create task</b>
+
+  # Required attributes
+  #   :name
+  
+  @task = Task.new params
+  @task.save
+
+<b>Update task</b>
+
+  @task.name = 'Create wireframes'
+  @task.save
+
+<b>Delete task</b>
+
+  Task.delete id
+  # or
+  @task.destroy
+
+=== Invoices
+
+<b>Find Invoices</b>
+
+  @invoices = Invoice.find :all         # returns all invoices
+  @invoice = Invoice.find id            # returns specific invoice
+
+<b>Create invoice</b>
+
+  # Required attributes
+  #   :contact_id
+  #   :project_id
+  #   :dated_on
+  #   :reference
+  #   :status
+  
+  @invoice = Invoice.new params
+  @invoice.save
+
+<b>Update invoice</b>
+
+  @invoice.status = 'Sent'
+  @invoice.save
+
+<b>Delete invoice</b>
+
+  Invoice.delete id
+  # or
+  @invoice.destroy
+
+<b>Changing status</b>
+
+  @invoice.mark_as_draft
+  @invoice.mark_as_sent
+  @invoice.mark_as_cancelled
+
+=== Invoice items
+
+<b>Find invoice items</b>
+
+  @invoice_items = InvoiceItem.find :all  # returns all invoice items
+  @invoice_item = InvoiceItem.find id     # returns specific invoice item
+
+<b>Create invoice item</b>
+
+  # Required attributes
+  #   :item_type                        # must be Hours, Days, Months, Years, Products, Services, Expenses, Discount, Credit, Comment
+  #   :description
+  #   :quantity
+  #   :price
+  #   :sales_tax_rate
+  
+  @invoice_item = InvoiceItem.new params
+  @invoice_item.save
+
+<b>Update invoice item</b>
+
+  @invoice_item.name = 'Create wireframes'
+  @invoice_item.save
+
+<b>Delete invoice item</b>
+
+  InvoiceItem.delete id
+  # or
+  @invoice_item.destroy
 
 === Timeslips
 
-  @timeslips = Timeslip.find_all              # returns all timeslips
-  @timeslips = Timeslip.find_all(project_id)  # returns all timeslips for project
-  @timeslip = Timeslip.find(timeslip_id)      # returns specific timeslip
+<b>Find timeslips</b>
+
+  @timeslips = Timeslip.find :all, :params => {:from => '2009-10-01', :to => '2009-10-30'}
+                                        # returns all timeslips (:from and :to dates required)
+  @timeslip = Timeslip.find id          # returns specific timeslip
+
+<b>Create timeslip</b>
+
+  # Required attributes
+  #   :user_id
+  #   :hours
+  #   :dated_on
+  #   :task_id OR :new_task
+  
+  @timeslip = Timeslip.new params
+  @timeslip.save
+
+<b>Update timeslip</b>
+
+  @timeslip.hours = '3.5'
+  @timeslip.save
+
+<b>Delete timeslip</b>
+
+  Timeslip.delete id
+  # or
+  @timeslip.destroy
 
 == Author
  

data/Rakefile

@@ -5,15 +5,14 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "freeagent_api"
-    gem.summary = %Q{Simple Ruby interface to the Freeagent Central API.}
-    gem.description = %Q{This is an early development version of a Ruby wrapper for the Freeagent API. Currently this only supports GET requests (POST will follow shortly) and not all API methods are currently supported (more will follow).}
+    gem.summary = %Q{ActiveResource Ruby wrapper for the Freeagent Central API.}
+    gem.description = %Q{This is an ActiveResource Ruby wrapper for the Freeagent API. Currently supports the following API resources: Company, Contacts, Projects, Tasks, Invoices, Invoice Items, Timeslips (more will follow).}
     gem.email = "aaron@gc4.co.uk"
     gem.homepage = "http://github.com/aaronrussell/freeagent_api"
     gem.authors = ["Aaron Russell"]
     gem.add_development_dependency "thoughtbot-shoulda"
-    gem.add_dependency "activesupport"
-    gem.add_dependency "nokogiri"
-    gem.add_dependency "api_cache"
+    gem.add_development_dependency "fakeweb"
+    gem.add_dependency "activeresource"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/freeagent_api.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{freeagent_api}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Aaron Russell"]
-  s.date = %q{2009-10-14}
-  s.description = %q{This is an early development version of a Ruby wrapper for the Freeagent API. Currently this only supports GET requests (POST will follow shortly) and not all API methods are currently supported (more will follow).}
+  s.date = %q{2009-10-27}
+  s.description = %q{This is an ActiveResource Ruby wrapper for the Freeagent API. Currently supports the following API resources: Company, Contacts, Projects, Tasks, Invoices, Invoice Items, Timeslips (more will follow).}
   s.email = %q{aaron@gc4.co.uk}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -25,17 +25,49 @@ Gem::Specification.new do |s|
      "VERSION",
      "freeagent_api.gemspec",
      "lib/freeagent_api.rb",
-     "test/freeagent_api_test.rb",
-     "test/test_helper.rb"
+     "test/authentication_test.rb",
+     "test/company_test.rb",
+     "test/contact_test.rb",
+     "test/invoice_item_test.rb",
+     "test/invoice_test.rb",
+     "test/project_test.rb",
+     "test/stubs/company/invoice_timeline",
+     "test/stubs/company/tax_timeline",
+     "test/stubs/contacts/find_all",
+     "test/stubs/contacts/find_single",
+     "test/stubs/http/200",
+     "test/stubs/http/201",
+     "test/stubs/invoice_items/find_all",
+     "test/stubs/invoice_items/find_single",
+     "test/stubs/invoices/find_all",
+     "test/stubs/invoices/find_single",
+     "test/stubs/projects/find_all",
+     "test/stubs/projects/find_single",
+     "test/stubs/projects/invoices",
+     "test/stubs/projects/timeslips",
+     "test/stubs/tasks/find_all",
+     "test/stubs/tasks/find_single",
+     "test/stubs/timeslips/find_all",
+     "test/stubs/timeslips/find_single",
+     "test/task_test.rb",
+     "test/test_helper.rb",
+     "test/timeslip_test.rb"
   ]
   s.homepage = %q{http://github.com/aaronrussell/freeagent_api}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Simple Ruby interface to the Freeagent Central API.}
+  s.summary = %q{ActiveResource Ruby wrapper for the Freeagent Central API.}
   s.test_files = [
-    "test/freeagent_api_test.rb",
-     "test/test_helper.rb"
+    "test/authentication_test.rb",
+     "test/company_test.rb",
+     "test/contact_test.rb",
+     "test/invoice_item_test.rb",
+     "test/invoice_test.rb",
+     "test/project_test.rb",
+     "test/task_test.rb",
+     "test/test_helper.rb",
+     "test/timeslip_test.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -44,19 +76,16 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
-      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
-      s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
-      s.add_runtime_dependency(%q<api_cache>, [">= 0"])
+      s.add_development_dependency(%q<fakeweb>, [">= 0"])
+      s.add_runtime_dependency(%q<activeresource>, [">= 0"])
     else
       s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
-      s.add_dependency(%q<activesupport>, [">= 0"])
-      s.add_dependency(%q<nokogiri>, [">= 0"])
-      s.add_dependency(%q<api_cache>, [">= 0"])
+      s.add_dependency(%q<fakeweb>, [">= 0"])
+      s.add_dependency(%q<activeresource>, [">= 0"])
     end
   else
     s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
-    s.add_dependency(%q<activesupport>, [">= 0"])
-    s.add_dependency(%q<nokogiri>, [">= 0"])
-    s.add_dependency(%q<api_cache>, [">= 0"])
+    s.add_dependency(%q<fakeweb>, [">= 0"])
+    s.add_dependency(%q<activeresource>, [">= 0"])
   end
 end

data/lib/freeagent_api.rb

@@ -1,172 +1,115 @@
 require 'rubygems'
-require 'nokogiri'
-require 'net/https'
-require 'api_cache'
-require 'activesupport'
+require 'activeresource'
 
 module Freeagent
   
   class << self
-    attr_accessor :domain, :username, :password
-
-    def self.domain=(domain)
-      @domain = domain
-    end
-
-    def self.username=(username)
-      @username = username
+    def authenticate(options)
+      Base.authenticate(options)
     end
+  end
+  
+  class Error < StandardError; end
 
-    def self.password=(password)
-      @password = password
+  class Base < ActiveResource::Base
+    def self.authenticate(options)
+      self.site = "https://#{options[:domain]}"
+      self.user = options[:username]
+      self.password = options[:password]
     end
   end
   
-  class Base
-    
-    def initialize(attributes={})
-      attributes.each do |key, value|
-        raise "no attr_accessor set for #{key} on #{self.class}" if !respond_to?("#{key}=")
-        self.send("#{key}=", value)
-      end
-    end
+  # Company
     
-    def self.get(path)
-      @@resp = APICache.get(path) do
-        http = Net::HTTP.new(Freeagent.domain, 443)
-        http.use_ssl = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-        http.start do |http|
-          request = Net::HTTP::Get.new(path, {'Content-Type' => 'application/xml', 'Accept' => 'application/xml'})
-          request.basic_auth(Freeagent.username, Freeagent.password)
-          response = http.request(request)
-          case response
-          when Net::HTTPSuccess
-            @@resp = response.body
-          else
-            response.error!
-            raise APICache::InvalidResponse
-          end
-        end
-      end
+  class Company
+    def self.invoice_timeline
+      InvoiceTimeline.find :all, :from => '/company/invoice_timeline.xml'
     end
-    
-    def self.parse(path, options)
-      response = []
-      Nokogiri::XML(@@resp).xpath(path).each do |ts|
-        res = {}
-        options.each do |key|
-          res[key.underscore.to_sym] = ts.xpath(key).text
-        end
-        response << self.new(res)
-      end
-      return response
+    def self.tax_timeline
+      TaxTimeline.find :all, :from => '/company/tax_timeline.xml'
     end
-    
+  end
+  class InvoiceTimeline < Base
+    self.prefix = '/company/'
+  end
+  class TaxTimeline < Base
+    self.prefix = '/company/'
   end
   
+  # Contacts
+  
   class Contact < Base
-    @elements = ['id', 'organisation-name', 'first-name', 'last-name', 'address1', 'address2', 'address3', 'town', 'region', 'country', 'postcode', 'phone-number', 'email', 'contact-name-on-invoices', 'sales-tax-registration_number', 'uses-contact-invoice-sequence']
-    @elements.each {|t| attr_accessor t.underscore.to_sym}
-    
-    def self.find_all
-      get '/contacts'
-      contacts = parse('contacts/contact', @elements)
-      return contacts
+  end
+  
+  # Projects
+  
+  class Project < Base
+
+    def invoices
+      Invoice.find :all, :from => "/projects/#{id}/invoices.xml"
     end
-    
-    def self.find(contact_id)
-      get '/contacts/'+contact_id
-      contacts = parse('contact', @elements)
-      return contacts[0]
+        
+    def timeslips
+      Timeslip.find :all, :from => "/projects/#{id}/timeslips.xml"
     end
+
+  end
+  
+  # Tasks - Complete
+  
+  class Task < Base
+    self.prefix = '/projects/:project_id/'        
   end
   
+  # Invoices - Complete
+  
   class Invoice < Base
-    @elements = ['id', 'contact-id', 'project-id', 'dated-on', 'due-on', 'reference', 'net-value', 'sales-tax-value', 'status', 'comments', 'discount-percent', 'omit-header', 'payment-terms', 'written-off-date', 'invoice-items']
-    @elements.each {|t| attr_accessor t.underscore.to_sym}
     
-    def self.find_all(project_id = false)
-      if project_id
-        get '/projects/'+project_id+'/invoices' 
-      else
-        get '/invoices'
+    def mark_as_draft
+      connection.put("/invoices/#{id}/mark_as_draft.xml", encode, self.class.headers).tap do |response|
+        load_attributes_from_response(response)
       end
-      invoices = parse('invoices/invoice', @elements)
-      return invoices.reverse
     end
-    
-    def self.find(invoice_id)
-      get '/invoices/'+invoice_id
-      invoices = parse('invoice', @elements)
-      invoices.each do |i|
-        i.invoice_items = InvoiceItem.find_all(invoice_id)
+    def mark_as_sent
+      connection.put("/invoices/#{id}/mark_as_sent.xml", encode, self.class.headers).tap do |response|
+        load_attributes_from_response(response)
       end
-      return invoices[0]
     end
-  end
-  
-  class InvoiceItem < Invoice
-    @elements = ['id', 'invoice-id', 'project-id', 'item-type', 'price', 'quantity', 'description', 'sales-tax-rate']
-    @elements.each {|t| attr_accessor t.underscore.to_sym}
-
-    def self.find_all(invoice_id)
-      items = parse('invoice/invoice-items/invoice-item', @elements)
-      return items
-    end
-  end
-  
-  class Project < Base
-    @elements = ['id', 'contact-id', 'name', 'billing-basis', 'budget', 'budget-units', 'invoicing-reference', 'is-ir35', 'normal-billing-rate', 'payment-terms-in-days', 'starts-on', 'ends-on', 'status', 'uses-project-invoice-sequence']
-    @elements.each {|t| attr_accessor t.underscore.to_sym}
-    
-    def self.find_all
-      get '/projects'
-      projects = parse('projects/project', @elements)
-      return projects
+    def mark_as_cancelled
+      connection.put("/invoices/#{id}/mark_as_cancelled.xml", encode, self.class.headers).tap do |response|
+        load_attributes_from_response(response)
+      end
     end
     
-    def self.find(project_id)
-      get '/projects/'+project_id
-      projects = parse('project', @elements)
-      return projects[0]
-    end
   end
   
-  class Task < Base
-    @elements = ['id', 'project-id', 'name']
-    @elements.each {|t| attr_accessor t.underscore.to_sym}
-
-    def self.find(project_id, task_id)
-      get '/projects/'+project_id+'/tasks/'+task_id
-      tasks = parse('task', @elements)
-      return tasks[0]
-    end
+  # Invoice items - Complete
+  
+  class InvoiceItem < Base
+    self.prefix = '/invoices/:invoice_id/'
   end
+
+  # Timeslips
   
   class Timeslip < Base
-    @elements = ['id', 'dated-on', 'project-id', 'task-id', 'task', 'user-id', 'hours', 'comment']
-    @elements.each {|t| attr_accessor t.underscore.to_sym}
-
-    def self.find_all(project_id = false)
-      if project_id
-        get '/projects/'+project_id+'/timeslips'
-      else
-        get '/timeslips'
+    
+    def self.find(*arguments)
+      scope   = arguments.slice!(0)
+      options = arguments.slice!(0) || {}
+      if options[:params] && options[:params][:from] && options[:params][:to]
+        options[:params][:view] = options[:params][:from]+'_'+options[:params][:to]
+        options[:params].delete(:from)
+        options[:params].delete(:to)
       end
-      timeslips = parse('timeslips/timeslip', @elements)
-      timeslips.each do |t|
-        t.task = Task.find(project_id, t.task_id)
+
+      case scope
+        when :all   then find_every(options)
+        when :first then find_every(options).first
+        when :last  then find_every(options).last
+        when :one   then find_one(options)
+        else             find_single(scope, options)
       end
-      return timeslips.reverse
-    end
-    
-    def self.find(timeslip_id)
-      get '/timeslips'+timeslip_id
-      timeslips = parse('timeslip', @elements)
-      return timeslips[0]
-    end
+    end    
   end
-  
-  
+
 end

data/test/authentication_test.rb

@@ -0,0 +1,13 @@
+require 'test_helper'
+
+class FreeagentApiTest < Test::Unit::TestCase
+  
+  context "Authentication details" do
+    should "match what was set" do
+      assert_equal URI.parse('https://testuser.freeagentcentral.com'), Base.site
+      assert_equal 'testuser', Base.user
+      assert_equal 'testpass', Base.password
+    end
+  end
+  
+end

data/test/company_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+
+class CompanyTest < Test::Unit::TestCase
+  
+  fake_it_all
+    
+  context "Invoice timeline" do
+    setup do
+      @inv_timeline = Company.invoice_timeline
+    end
+    should "return an array" do
+      assert @inv_timeline.is_a? Array
+    end
+    should "return invoice timeline items" do
+      assert_equal 12, @inv_timeline.size
+      assert @inv_timeline.first.is_a? InvoiceTimeline
+    end    
+  end
+  
+  context "Tax timeline" do
+    setup do
+      @tax_timeline = Company.tax_timeline
+    end
+    should "return an array" do
+      assert @tax_timeline.is_a? Array
+    end
+    should "return projects" do
+      assert_equal 3, @tax_timeline.size
+      assert @tax_timeline.first.is_a? TaxTimeline
+    end    
+  end
+    
+end