free_agent 0.1.0

data/README

@@ -0,0 +1,53 @@
+FreeAgent API
+=============
+
+This is just a simple wrapper around the FreeAgent[1] API. The motivation is that I wanted to be able to deal with multiple FreeAgent accounts; most other approaches use ActiveResource-esque mappings that link Projects (for example) to a single account.
+
+Example use:
+
+  require 'rubygems'
+  require 'free_agent'
+  
+  Lazyatom = FreeAgent::Company.new("mydomain", "me@email.com", "mypassword")
+  
+  # All my contacts
+  Lazyatom.contacts.all
+  
+  # All my unpaid invoices
+  Lazyatom.invoices.reject { |i| i.paid? }
+  
+  # All the timeslips for a project
+  Lazyatom.projects.first.timeslips.all
+
+It's early days yet, but this is a nice start.
+
+
+Links
+-----
+
+[1]: http://www.freeagentcentral.com/?referrer=31h0wcs9
+
+
+
+Copyright (c) 2010 James Adam
+Plenty of help from Free Rangers, incl. Luke Redpath
+ 
+The MIT License
+ 
+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/free_agent.rb

@@ -0,0 +1,252 @@
+require 'restclient'
+require 'crack'
+require 'mash'
+require 'active_support/core_ext/string'
+require 'active_support/core_ext/object/returning'
+require 'active_support/core_ext/hash'
+require 'cgi'
+
+RestClient::Resource.class_eval do
+  def root
+    self.class.new(URI.parse(url).merge('/').to_s, options)
+  end
+end
+
+module FreeAgent
+  class Company
+    def initialize(domain, username, password)
+      @resource = RestClient::Resource.new(
+        "https://#{domain}.freeagentcentral.com",
+        :user => username, :password => password
+      )
+    end
+
+    def invoices
+      @invoices ||= Collection.new(@resource['/invoices'], :entity => :invoice)
+    end
+
+    def contacts
+      @contacts ||= Collection.new(@resource['/contacts'], :entity => :contact)
+    end
+
+    def projects
+      @projects ||= Collection.new(@resource['/projects'], :entity => :project)
+    end
+
+    def users
+      @users ||= Collection.new(@resource['/company/users'], :entity => :user)
+    end
+
+    # Note, this is only for PUT/POSTing to
+    def timeslips
+      @timeslips ||= Collection.new(@resource['/timeslips'], :entity => :timeslip)
+    end
+
+    def expenses(user_id, options={})
+      options.assert_valid_keys(:view, :from, :to)
+      options.reverse_merge!(:view => 'recent')
+
+      if options[:from] && options[:to]
+        options[:view] = "#{options[:from].strftime('%Y-%m-%d')}_#{options[:to].strftime('%Y-%m-%d')}"
+      end
+
+      Collection.new(@resource["/users/#{user_id}/expenses?view=#{options[:view]}"], :entity => :expense)
+    end
+  end
+
+  class Collection
+    include Enumerable
+
+    def initialize(resource, options={})
+      @resource = resource
+      @entity = options.delete(:entity)
+      @entity_klass = "FreeAgent::#{@entity.to_s.classify}".constantize
+    end
+
+    def url
+      @resource.url
+    end
+
+    def find(id=nil)
+      if id
+        entity_for_id(id).reload
+      else
+        super
+      end
+    end
+
+    def each(&block)
+      all.each(&block)
+    end
+
+    def all(params={})
+      if params.any?
+        # very naive Hash-to-params
+        resource = @resource['?'+params.map{|k,v|"#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"}.join('&')]
+      else
+        resource = @resource
+      end
+      case (response = resource.get).code
+      when 200
+        if entities = Crack::XML.parse(response)[@entity.to_s.pluralize]
+          entities.map do |attributes|
+            entity_for_id(attributes['id'], attributes)
+          end
+        else
+          []
+        end
+      end
+    end
+
+    def create(attributes)
+      payload = attributes.to_xml(:root => @entity.to_s )
+      case (response = @resource.post(payload,
+        :content_type => 'application/xml', :accept => 'application/xml')).code
+      when 201
+        resource_path = URI.parse(response.headers[:location]).path
+        @entity_klass.new(@resource.root[resource_path]).reload
+      end
+    end
+
+    def update(id, attributes)
+      entity_for_id(id).update(attributes, headers)
+    end
+
+    def destroy(id)
+      entity_for_id(id).destroy
+    end
+
+    private
+
+    def entity_for_id(id, attributes={})
+      @entity_klass.new(@resource["/#{id}"], attributes)
+    end
+
+    # Treat the collection as if it's an array otherwise
+    def method_missing(method, *args, &block)
+      all.send(method, *args, &block)
+    end
+  end
+
+  class Entity
+    def self.has_many(things)
+      define_method(things) do
+        Collection.new(@resource["/#{things}"], :entity => things.to_s.singularize)
+      end
+    end
+
+    def self.belongs_to(thing, *args)
+      define_method(thing) do
+
+      end
+      # NOOP right now.
+    end
+
+    def self.xml_name
+      name.split("::")[1..-1].join("::").underscore
+    end
+
+    attr_reader :attributes
+
+    def initialize(resource, attributes = {})
+      @resource = resource
+      @attributes = attributes.to_mash
+    end
+
+    def id
+      @attributes.id
+    end
+
+    def url
+      @resource.url
+    end
+
+    def reload
+      returning(self) do
+        @attributes = Crack::XML.parse(@resource.get)[xml_name].to_mash
+      end
+    end
+
+    def update(new_attributes)
+      attributes.merge!(new_attributes)
+      save
+    end
+
+    def save
+      @resource.put(attributes.to_xml(:root => xml_name),
+        :content_type =>'application/xml', :accept => 'application/xml')
+    end
+
+    def destroy
+      @resource.delete
+    end
+
+    private
+
+    def xml_name
+      self.class.xml_name
+    end
+
+    def method_missing(*args)
+      @attributes.send(*args)
+    end
+  end
+
+  class User < Entity
+    has_many :expenses
+    has_many :timeslips
+  end
+
+  class Project < Entity
+    has_many :tasks
+    has_many :invoices
+    has_many :timeslips
+    belongs_to :contact
+
+    def active?
+      status == "Active"
+    end
+  end
+
+  class Invoice < Entity
+    has_many :invoice_items
+    belongs_to :project
+    belongs_to :contact
+  end
+
+  class InvoiceItem < Entity
+  end
+
+  class Task < Entity
+    belongs_to :project
+  end
+
+  class Timeslip < Entity
+    def initialize(resource, attributes={})
+      # need to convert /projects/123/timeslips/456 into /timeslips/456
+      tweaked_resource = RestClient::Resource.new(resource.url.gsub(/\/projects\/\d+\//, "/"), resource.options)
+      super(tweaked_resource, attributes)
+    end
+
+    belongs_to :project
+    belongs_to :user
+    belongs_to :task
+  end
+
+  class Contact < Entity
+    has_many :invoices
+    has_many :projects
+  end
+
+  class Bill < Entity
+    belongs_to :contact
+    belongs_to :project, :key => :rebilled_to_project_id
+  end
+
+  class Expense < Entity
+    belongs_to :user
+  end
+
+  class Attachment < Entity
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: free_agent
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- James Adam
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-17 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: crack
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mash
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: james@lazyatom.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+- lib/free_agent.rb
+has_rdoc: true
+homepage: http://interblah.net/freeagent-gem
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: freeagent
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A small ruby library for accessing information from http://freeagentcentral.com
+test_files: []
+