freeagent 0.1.0 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,6 +1,23 @@
 = Changelog
 
 
+== Release 0.2.0
+
+* NEW: Added support for Project#invoices.
+
+* NEW: Added support for Task records.
+
+* NEW: Added Contact validations.
+
+* NEW: Added Dynamic Finders feature.
+
+* NEW: Added support for Contact#invoices.
+
+* NEW: Added support for Invoice status methods.
+
+* CHANGED: Added .gemspec description and summary.
+
+
 == Release 0.1.0
 
 * Initial version

data/Gemfile.lock

@@ -6,25 +6,26 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    activemodel (3.0.6)
-      activesupport (= 3.0.6)
+    activemodel (3.0.7)
+      activesupport (= 3.0.7)
       builder (~> 2.1.2)
       i18n (~> 0.5.0)
-    activeresource (3.0.6)
-      activemodel (= 3.0.6)
-      activesupport (= 3.0.6)
-    activesupport (3.0.6)
+    activeresource (3.0.7)
+      activemodel (= 3.0.7)
+      activesupport (= 3.0.7)
+    activesupport (3.0.7)
     builder (2.1.2)
     diff-lcs (1.1.2)
     i18n (0.5.0)
     json (1.5.1)
-    mimic (0.4.1)
+    mimic (0.4.2)
       json
       plist
       rack
       sinatra
     plist (3.1.0)
     rack (1.2.2)
+    rr (1.0.2)
     rspec (2.5.0)
       rspec-core (~> 2.5.0)
       rspec-expectations (~> 2.5.0)
@@ -33,10 +34,10 @@ GEM
     rspec-expectations (2.5.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.5.0)
-    sinatra (1.2.1)
+    sinatra (1.2.3)
       rack (~> 1.1)
-      tilt (< 2.0, >= 1.2.2)
-    tilt (1.2.2)
+      tilt (>= 1.2.2, < 2.0)
+    tilt (1.3)
     yard (0.6.7)
 
 PLATFORMS
@@ -46,5 +47,6 @@ DEPENDENCIES
   activeresource (>= 3.0.0)
   freeagent!
   mimic
+  rr
   rspec (~> 2.5.0)
   yard

data/README.rdoc

@@ -1,6 +1,13 @@
 = FreeAgent Client
 
-(Unofficial) Ruby client for the {FreeAgent Central API}[http://www.freeagentcentral.com/developers/freeagent-api].
+(Unofficial) Ruby client for the {FreeAgent}[http://fre.ag/4103hsny] accounting software.
+
+
+== Status
+
+This library is a work in progress.
+
+Visit the {FreeAgent Central API}[http://www.freeagentcentral.com/developers/freeagent-api] page to learn more about FreeAgent API.
 
 
 == Requirements
@@ -19,6 +26,11 @@
 * {Simone Carletti}[http://www.simonecarletti.com] <weppos@weppos.net>
 
 
+== Promo
+
+Sign up with this {promo link}[http://fre.ag/4103hsny] and save 10% on the standard FreeAgent monthly price... forever!
+
+
 == License
 
 FreeAgent (the Client) is Copyright (c) 2011 Simone Carletti.

data/TODO

@@ -0,0 +1,22 @@
+/verify
+
+/company/invoice_timeline
+/company/tax_timeline
+
+/bills/types
+
+/projects/project_id/timeslip
+
+/timeslips
+
+/company/users
+
+/users/user_id/expenses
+
+/expenses/types
+
+?
+
+/projects/project_id/notes
+/projects/project_id/expenses
+/projects/project_id/estimates

data/freeagent.gemspec

@@ -5,15 +5,15 @@ require "free_agent/version"
 Gem::Specification.new do |s|
   s.name        = "freeagent"
   s.version     = FreeAgent::VERSION
-  s.summary     = ""
-  s.description = ""
+  s.summary     = "Ruby client for the FreeAgent API."
+  s.description = "Ruby client for the FreeAgent API."
 
   s.platform    = Gem::Platform::RUBY
   s.required_ruby_version = ">= 1.8.7"
 
   s.authors     = ["Simone Carletti"]
   s.email       = ["weppos@weppos.net"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/weppos/freeagent"
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
@@ -24,4 +24,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency("yard")
   s.add_development_dependency("activeresource", ">= 3.0.0")
   s.add_development_dependency("mimic")
+  s.add_development_dependency("rr")
 end

data/lib/free_agent.rb

@@ -13,6 +13,7 @@ module FreeAgent
   autoload :Invoice,      'free_agent/invoice'
   autoload :InvoiceItem,  'free_agent/invoice_item'
   autoload :Project,      'free_agent/project'
+  autoload :Task,         'free_agent/task'
 
 
   class << self

data/lib/free_agent/base.rb

@@ -1,6 +1,138 @@
 module FreeAgent
 
+  # The Base class for any FreeAgent resource.
+  #
+  # == Dynamic Finders
+  #
+  # Like ActiveRecord, this class support dynamic finders.
+  # You can use dynamic finders to search a resource by any of its attributes.
+  #
+  #   class Contact < Base
+  #   end
+  #
+  #   Contact.find_by_email 'email@example.org'
+  #   Contact.find_by_username_and_email 'weppos', 'email@example.org'
+  #
+  # However, there's one important caveat we should mention.
+  # This feature is not very efficient and the more records you have,
+  # the longer the query it takes.
+  #
+  # This is because record filtering is performed client-side.
+  # The library first loads and instantiate all records, then it filters them
+  # applying given criteria.
+  #
   class Base < ActiveResource::Base
+
+    # = Active Record Dynamic Finder Match
+    #
+    # Refer to ActiveRecord::Base documentation for Dynamic attribute-based finders for detailed info.
+    #
+    class DynamicFinderMatch
+      def self.match(method)
+        finder       = :first
+        bang         = false
+        instantiator = nil
+
+        case method.to_s
+        when /^find_(all_|last_)?by_([_a-zA-Z]\w*)$/
+          finder = :last if $1 == 'last_'
+          finder = :all if $1 == 'all_'
+          names = $2
+        when /^find_by_([_a-zA-Z]\w*)\!$/
+          bang = true
+          names = $1
+        when /^find_or_(initialize|create)_by_([_a-zA-Z]\w*)$/
+          instantiator = $1 == 'initialize' ? :new : :create
+          names = $2
+        else
+          return nil
+        end
+
+        new(finder, instantiator, bang, names.split('_and_'))
+      end
+
+      def initialize(finder, instantiator, bang, attribute_names)
+        @finder          = finder
+        @instantiator    = instantiator
+        @bang            = bang
+        @attribute_names = attribute_names
+      end
+
+      attr_reader :finder, :attribute_names, :instantiator
+
+      def finder?
+        @finder && !@instantiator
+      end
+
+      def instantiator?
+        @finder == :first && @instantiator
+      end
+
+      def creator?
+        @finder == :first && @instantiator == :create
+      end
+
+      def bang?
+        @bang
+      end
+    end
+
+
+    class << self
+
+      protected
+
+        def method_missing(method_id, *arguments, &block)
+          if match = DynamicFinderMatch.match(method_id)
+            attribute_names = match.attribute_names
+            if match.finder?
+              find_by_attributes(match, attribute_names, *arguments)
+            elsif match.instantiator?
+              find_or_instantiator_by_attributes(match, attribute_names, *arguments, &block)
+            end
+          else
+            super
+          end
+        end
+
+        def find_by_attributes(match, attributes, *args)
+          conditions = Hash[attributes.map {|a| [a, args[attributes.index(a)]]}]
+          result = all.select do |record|
+            conditions.all? { |k,v| record.send(k) == v }
+          end
+          result = result.send(match.finder) if match.finder != :all
+
+          if match.bang? && result.blank?
+            raise ActiveResource::ResourceNotFound, 404, "Couldn't find #{self} with #{conditions.to_a.collect {|p| p.join(' = ')}.join(', ')}"
+          else
+            result
+          end
+        end
+
+        def find_or_instantiator_by_attributes(match, attributes, *args)
+          record = find_by_attributes(match, attributes, *args)
+
+          unless record
+            conditions = Hash[attributes.map {|a| [a, args[attributes.index(a)]]}]
+            record = new(conditions)
+            yield(record) if block_given?
+            record.save if match.instantiator == :create
+          end
+
+          record
+        end
+
+    end
+
+
+    def respond_to?(method_id, include_private = false)
+      if DynamicFinderMatch.match(method_id)
+        return true
+      end
+
+      super
+    end
+
   end
 
 end

data/lib/free_agent/contact.rb

@@ -1,7 +1,75 @@
 module FreeAgent
 
   # Represents a Contact in FreeAgent.
+  #
+  # @attr [String] first_name
+  # @attr [String] last_name
+  # @attr [String] organisation_name
+  #
   class Contact < Base
+
+    # == Methods
+    #
+    # * .all
+    # * .first
+    # * .last
+    # * .find(id)
+    # * .new
+    # * .create
+    #
+    # * #save
+    # * #update
+    # * #destroy
+    #
+    # == Relationships
+    #
+    # - has_many :bills
+    # - has_many :estimates
+    # - has_many :projects
+    # * has_many :invoices
+
+
+    validates_presence_of :first_name, :unless => :organisation_name?
+    validates_presence_of :last_name,  :unless => :organisation_name?
+    validates_presence_of :organisation_name, :unless => :name?
+
+    schema do
+      attribute :first_name,        :string
+      attribute :last_name,         :string
+      attribute :organisation_name, :string
+    end
+
+
+    # Creates the name of the contact,
+    # composed by the interpolation of {#first_name} and {#last_name}.
+    #
+    # @return [String,nil] The Contact name.
+    def name
+      attrs = [first_name, last_name].reject(&:blank?)
+      attrs.empty? ? nil : attrs.join(" ")
+    end
+
+    alias :name? :name
+
+
+    # Gets all the invoices associated to this contact.
+    #
+    # @overload invoices(options = {})
+    #   Gets all the invoices for this contact.
+    #   @param [Hash] options Hash of options to customize the finder behavior.
+    #   @return [Array<FreeAgent::Invoice>]
+    #
+    # @example Simple query
+    #   contact.invoices
+    #   # => [...]
+    # @example Query with custom find params
+    #   contact.invoices(:params => { :foo => 'bar' }
+    #   # => [...]
+    #
+    def invoices(*args)
+      options = args.extract_options!
+      Invoice.all(options.merge!(:from => "/contacts/#{id}/invoices.xml"))
+    end
   end
 
 end

data/lib/free_agent/invoice.rb

@@ -2,6 +2,64 @@ module FreeAgent
 
   # Represents an Invoice in FreeAgent.
   class Invoice < Base
+
+    # == Methods
+    #
+    # * .all
+    # * .first
+    # * .last
+    # * .find(id)
+    # * .new
+    # * .create
+    #
+    # * #save
+    # * #update
+    # * #destroy
+    # * #mark_as_draft
+    # * #mark_as_sent
+    # * #mark_as_cancelled
+
+    # Marks the current invoice as draft.
+    #
+    # This method actually performs a new HTTP request
+    # to FreeAgent in order to execute the update.
+    #
+    # @return [void]
+    def mark_as_draft
+      # put(:mark_as_draft).tap do |response|
+      #   load_attributes_from_response(response)
+      # end
+      put(:mark_as_draft) && reload
+    end
+
+    # Marks the current invoice as sent.
+    #
+    # This method actually performs a new HTTP request
+    # to FreeAgent in order to execute the update.
+    # It also triggers any automatic deliver if the
+    # {#send_new_invoice_emails} invoice attribute is set to true.
+    #
+    # @return [void]
+    def mark_as_sent
+      # put(:mark_as_sent).tap do |response|
+      #   load_attributes_from_response(response)
+      # end
+      put(:mark_as_sent) && reload
+    end
+
+    # Marks the current invoice as cancelled.
+    #
+    # This method actually performs a new HTTP request
+    # to FreeAgent in order to execute the update.
+    #
+    # @return [void]
+    def mark_as_cancelled
+      # put(:mark_as_cancelled).tap do |response|
+      #   load_attributes_from_response(response)
+      # end
+      put(:mark_as_cancelled) && reload
+    end
+
   end
 
 end

data/lib/free_agent/project.rb

@@ -2,6 +2,26 @@ module FreeAgent
 
   # Represents a Project in FreeAgent.
   class Project < Base
+
+    # Gets all the invoices associated to this project.
+    #
+    # @overload invoices(options = {})
+    #   Gets all the invoices for this project.
+    #   @param [Hash] options Hash of options to customize the finder behavior.
+    #   @return [Array<FreeAgent::Invoice>]
+    #
+    # @example Simple query
+    #   project.invoices
+    #   # => [...]
+    # @example Query with custom find params
+    #   project.invoices(:params => { :foo => 'bar' }
+    #   # => [...]
+    #
+    def invoices(*args)
+      options = args.extract_options!
+      Invoice.all(options.merge!(:from => "/projects/#{id}/invoices.xml"))
+    end
+
   end
 
 end