turingstudio-freshbooks-rb 3.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2009-02-18
+
+* 1 major enhancement:
+  * Initial release

data/README.rdoc

@@ -0,0 +1,65 @@
+= freshbooks-rb
+
+http://github.com/turingstudio/freshbooks-rb/
+
+== DESCRIPTION:
+
+A Ruby interface to the FreshBooks API. It exposes easy-to-use classes and methods for interacting with your FreshBooks account.
+
+== SYNOPSIS:
+
+Initialization:
+
+  FreshBooks::Base.setup('sample.freshbooks.com', 'mytoken')
+
+Updating a client name:
+
+  clients = FreshBooks::Client.list
+  client = clients[0]
+  client.first_name = 'Suzy'
+  client.update
+
+Updating an invoice:
+
+  invoice = FreshBooks::Invoice.get(4)
+  invoice.lines[0].quantity += 1
+  invoice.update
+
+Creating a new item
+
+  item = FreshBooks::Item.new
+  item.name = 'A sample item'
+  item.create
+ 
+== REQUIREMENTS:
+
+ activesupport >= 2.2.2
+
+== INSTALL:
+
+gem install turingstudio-freshbooks-rb
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 The Turing Studio, Inc.
+
+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/Rakefile

@@ -0,0 +1,20 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/freshbooks/version'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('freshbooks-rb', FreshBooks::VERSION) do |p|
+  p.developer('The Turing Studio, Inc.', 'support@turingstudio.com')
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [
+    ['xml-simple','>= 1.0.11'],
+    ['activesupport','>= 2.2.2']
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }

data/lib/freshbooks.rb

@@ -0,0 +1,41 @@
+#
+# Usage:
+#
+# FreshBooks::Base.setup('sample.freshbooks.com', 'mytoken')
+#
+# clients = FreshBooks::Client.list
+# client = clients[0]
+# client.first_name = 'Suzy'
+# client.update
+#
+# invoice = FreshBooks::Invoice.get(4)
+# invoice.lines[0].quantity += 1
+# invoice.update
+#
+# item = FreshBooks::Item.new
+# item.name = 'A sample item'
+# item.create
+#
+
+$:.unshift(File.dirname(__FILE__))
+
+require 'net/https'
+require 'rexml/document'
+require 'activesupport'
+
+require 'freshbooks/version'
+require 'freshbooks/response'
+require 'freshbooks/base'
+require 'freshbooks/category'
+require 'freshbooks/client'
+require 'freshbooks/estimate'
+require 'freshbooks/expense'
+require 'freshbooks/invoice'
+require 'freshbooks/item'
+require 'freshbooks/line'
+require 'freshbooks/payment'
+require 'freshbooks/project'
+require 'freshbooks/recurring'
+require 'freshbooks/staff'
+require 'freshbooks/task'
+require 'freshbooks/time_entry'

data/lib/freshbooks/base.rb

@@ -0,0 +1,286 @@
+module FreshBooks
+  class Base
+    class InternalError < Exception; end;
+    class AuthenticationError < Exception; end;
+    class UnknownSystemError < Exception; end;
+    class InvalidParameterError < Exception; end;
+    
+    attr_accessor :resp
+
+    def initialize(data = {})
+      @old_values = {}
+      @changed_fields = []
+      data.each do |name, value|
+        send("#{name}=", value) if self.class.attributes[name]
+      end
+    end
+    
+    # Convert an instance of this class to an XML element
+    def to_xml(elem_name = nil)
+      root = REXML::Element.new(node_name)
+      
+      self.class.attributes.each do |name, options|
+        next if options[:read_only] || !send("#{name}_changed?")
+
+        value = send(name)
+
+        if self.class.method_defined?("#{name}_to_xml")
+          send("#{name}_to_xml", root)
+        elsif value.is_a?(Array)
+          unless value.empty?
+            node = root.add_element(name.to_s)
+            value.each do |item|
+              node.add_element(item.to_xml)
+            end
+          end
+        elsif !value.nil?
+          root.add_element(name.to_s).text = value
+        end
+      end
+      
+      root
+    end
+        
+    def create
+      self.class.ensure_allowed! :create
+      resp = Base.call_api("#{node_name}.create", node_name => self)
+      if resp.success?
+        self.send("#{node_name}_id=", resp.elements[1].text.to_i)
+      end
+      resp.success? ? self.send("#{node_name}_id") : nil
+    end
+    
+    def update
+      self.class.ensure_allowed! :update
+      resp = Base.call_api("#{node_name}.update", node_name => self)
+      resp.success?
+    end
+    
+    def delete
+      self.class.delete(self.send("#{node_name}_id"))
+    end
+    
+    def send_by_email
+      self.class.send_by_email(self.send("#{node_name}_id"))
+    end
+    
+    def send_by_snail_mail
+      self.class.send_by_snail_mail(self.send("#{node_name}_id"))
+    end
+    
+    def node_name
+      self.class.node_name
+    end
+    
+    class << self
+      def setup(account_url, auth_token, request_headers = {})
+        @@account_url = account_url
+        @@auth_token = auth_token
+        @@request_headers = request_headers
+        @@response = nil
+      end
+      
+      def list(options = {})
+        ensure_allowed! :list
+        resp = Base.call_api("#{node_name}.list", options)
+        return nil unless resp.success?
+
+        elems = resp.elements[1].elements
+        elems.map { |elem| self.new_from_xml(elem) }
+      end
+      
+      def get(id)
+        ensure_allowed! :get
+        resp = Base.call_api("#{node_name}.get", "#{node_name}_id" => id)
+        resp.success? ? self.new_from_xml(resp.elements[1]) : nil
+      end
+            
+      def delete(id)
+        ensure_allowed! :delete
+        resp = Base.call_api("#{node_name}.delete", "#{node_name}_id" => id)
+        resp.success?
+      end
+      
+      def send_by_email(id)
+        ensure_allowed! :send_by_email
+        resp = Base.call_api("#{node_name}.sendByEmail", "#{node_name}_id" => id)
+        resp.success?
+      end
+      
+      def send_by_snail_mail(id)
+        ensure_allowed! :send_by_snail_mail
+        resp = Base.call_api("#{node_name}.sendBySnailMail", "#{node_name}_id" => id)
+        resp.success?
+      end
+      
+      def node_name
+        self.to_s.split('::').last.underscore
+      end
+      
+      #
+      # Defines structure attribute. Generates attr_accessor and #{name}_changed? method
+      #
+      # class Test < Base
+      #   attribute :test_id, :integer
+      # end
+      #
+      # test = Test.new
+      # test.test_id_changed?  # false
+      # test.test_id = 1
+      # test.test_id_changed?  # true
+      # test.test_id           # 1
+      #
+      def attribute(name, type, options = {})
+        self.attributes[name] = options.update(:type => type)
+        
+        define_method("#{name}=") do |value|
+          @changed_fields << name
+          @old_values[name] = send(name) if @old_values[name].nil?
+          instance_variable_set("@#{name}", value)
+        end
+        
+        define_method("#{name}_changed?") do
+          @changed_fields.include?(name)
+        end
+        
+        self.send(:attr_reader, name)
+      end
+      
+      def attributes
+        @attributes ||= {}
+      end
+      
+      #
+      # Generates association methods.
+      #
+      # class Test < Base
+      #   belongs_to :project
+      #   has_many :items, :lines
+      # end
+      #
+      # test = Test.new
+      # test.project      # Project.get(test.project_id)
+      # test.items        # Item.list(:test_id => test.test_id)
+      # test.lines        # Line.list(:test_id => test.test_id)
+      #
+      def has_many(*args)
+        args.each do |name|
+          class_eval "def #{name}(options = {}); @#{name} ||= #{name.to_s.classify}.list(options.merge('#{node_name}_id' => #{node_name}_id)); end"
+        end
+      end
+      
+      def belongs_to(*args)
+        args.each do |name|
+          class_eval "def #{name}(options = {}); @#{name} ||= #{name.to_s.classify}.get(#{name}_id); end"
+        end
+      end
+      
+      #
+      # Defines allowed API methods.
+      #
+      # class Test < Base
+      #   method :list
+      # end
+      #
+      # Test.list         # [...]
+      # Test.get(1)       # "Error: Method get is not allowed for Test"
+      #
+      def method(*args)
+        @methods = (methods + args).uniq
+      end
+      
+      def methods
+        @methods ||= []
+      end
+      
+      def ensure_allowed!(name)
+        unless methods.include?(name)
+          raise "Error: Method #{name} is not allowed for #{self}"
+        end
+      end
+      
+      # Create a new instance of this class from an XML element
+      def new_from_xml(xml_root)
+        object = self.new
+        attributes.each do |name, options|
+          node = xml_root.elements[name.to_s]
+          next if node.nil?
+
+          case options[:type]
+          when :integer
+            value = node.text.to_i
+          when :float
+            value = node.text.to_f
+          when :array
+            value = node.elements.map do |item|
+              FreshBooks::const_get(item.name.classify)::new_from_xml(item)
+            end
+          else
+            value = node.text.to_s
+          end
+          
+          object.send("#{name}=", value)
+        end
+        object
+      end
+      
+      def call_api(method, elems = [])
+        doc = REXML::Document.new '<?xml version="1.0" encoding="UTF-8"?>'
+        request = doc.add_element 'request'
+        request.attributes['method'] = method
+
+        elems.each do |key, value|
+          if value.is_a?(Base)
+            elem = value.to_xml
+            request.add_element(elem)
+          else
+            request.add_element(REXML::Element.new(key)).text = value.to_s
+          end
+        end
+           
+        result = self.post(request.to_s)
+        
+        @@response = Response.new(result)
+
+        #
+        # Failure
+        #
+        if @@response.fail?
+          error_msg = @@response.error_msg
+
+          raise InternalError.new,         error_msg if error_msg =~ /not formatted correctly/
+          raise AuthenticationError.new,   error_msg if error_msg =~ /[Aa]uthentication failed/
+          raise UnknownSystemError.new,    error_msg if error_msg =~ /does not exist/
+          raise InvalidParameterError.new, error_msg if error_msg =~ /Invalid parameter: (.*)/
+
+          # Raise an exception for unexpected errors
+          raise error_msg
+        end
+
+        @@response
+      end
+            
+      def response
+        @@response
+      end
+
+      def post(body)
+        connection = Net::HTTP.new(@@account_url, 443)
+        connection.use_ssl = true
+        connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+        request = Net::HTTP::Post.new(FreshBooks::SERVICE_URL)
+        request.basic_auth @@auth_token, 'X'
+        request.body = body
+        request.content_type = 'application/xml'
+        @@request_headers.each_pair do |name, value|
+          request[name.to_s] = value
+        end
+
+        result = connection.start { |http| http.request(request) }
+
+        result.body
+      end
+    end
+  end
+end

data/lib/freshbooks/category.rb

@@ -0,0 +1,11 @@
+module FreshBooks
+  class Category < Base
+    attribute :category_id, :integer
+    attribute :name,        :string
+    attribute :tax1,        :integer
+    attribute :tax2,        :integer
+    
+    has_many :expenses
+    method :list, :get, :create, :update, :delete
+  end
+end

data/lib/freshbooks/client.rb

@@ -0,0 +1,32 @@
+module FreshBooks
+  class Client < Base
+    attribute :client_id,     :integer
+    attribute :first_name,    :string
+    attribute :last_name,     :string
+    attribute :organization,  :string
+    attribute :email,         :string
+    attribute :username,      :string
+    attribute :password,      :string
+    attribute :work_phone,    :string
+    attribute :home_phone,    :string
+    attribute :mobile,        :string
+    attribute :fax,           :string
+    attribute :notes,         :string
+    attribute :p_street1,     :string
+    attribute :p_street2,     :string
+    attribute :p_city,        :string
+    attribute :p_state,       :string
+    attribute :p_country,     :string
+    attribute :p_code,        :string
+    attribute :s_street1,     :string
+    attribute :s_street2,     :string
+    attribute :s_city,        :string
+    attribute :s_state,       :string
+    attribute :s_country,     :string
+    attribute :s_code,        :string
+    attribute :url,           :string, :read_only => true
+    
+    has_many :expenses, :estimates, :invoices, :payments, :projects, :recurrings
+    method :list, :get, :create, :update, :delete
+  end
+end