freshbooks.rb 3.0.18 → 3.0.25

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA1: 
+  data.tar.gz: 298b0e8370286fe4a1ab625edf137ecf67cc7873
+  metadata.gz: 1cd14616e90a9f14b70982739d87b7e728b65bf2
+SHA512: 
+  data.tar.gz: 5d7c77d67d5bc1773ccc33580c1ce21fe115be11e4e51002218555df4f50be8d1919fa45ae7c11bf008887950d9dd66105c4c157829e3af43b5acbf12a9c7a36
+  metadata.gz: ada57b413deb19cfcf39756563d5c2a42681fd01345d2377156c6325bc9d8a19c6e7b1e9fdf7f0cd865144d4222a6675f1eda01c27b5aba58d6e52e3c653b662

data/History.txt

@@ -1,3 +1,11 @@
+== 2011-11-20
+  * Updated API to include currency code & language (In most API calls) [anlek]
+  * Updated time_entry to include "billed" attribute [anlek]
+  * Added new API calls: Gateway, Language, System, Tax [anlek]
+  * Added Staff.current [anlek]
+  * Added gateway_transaction to payment [anlek]
+  * Ensured that deprecated items are no longer included in the results (This MIGHT break some existing code) [anlek]
+
 == 0.0.1 2009-02-25
 
 * 3.0 major enhancement:

data/Manifest.txt

@@ -1,17 +1,29 @@
 History.txt
 LICENSE
 Manifest.txt
-README
+README.md
 Rakefile
+freshbooks.rb.gemspec
 lib/freshbooks.rb
+lib/freshbooks/address.rb
+lib/freshbooks/api.rb
+lib/freshbooks/autobill.rb
 lib/freshbooks/base.rb
+lib/freshbooks/budget.rb
+lib/freshbooks/card.rb
 lib/freshbooks/category.rb
 lib/freshbooks/client.rb
 lib/freshbooks/connection.rb
+lib/freshbooks/contact.rb
+lib/freshbooks/credits.rb
 lib/freshbooks/estimate.rb
 lib/freshbooks/expense.rb
+lib/freshbooks/expiration.rb
+lib/freshbooks/gateway.rb
+lib/freshbooks/gateway_transaction.rb
 lib/freshbooks/invoice.rb
 lib/freshbooks/item.rb
+lib/freshbooks/language.rb
 lib/freshbooks/line.rb
 lib/freshbooks/links.rb
 lib/freshbooks/list_proxy.rb
@@ -22,7 +34,9 @@ lib/freshbooks/response.rb
 lib/freshbooks/schema/definition.rb
 lib/freshbooks/schema/mixin.rb
 lib/freshbooks/staff.rb
+lib/freshbooks/system.rb
 lib/freshbooks/task.rb
+lib/freshbooks/tax.rb
 lib/freshbooks/time_entry.rb
 lib/freshbooks/xml_serializer.rb
 lib/freshbooks/xml_serializer/serializers.rb
@@ -30,10 +44,15 @@ script/console
 script/destroy
 script/generate
 test/fixtures/freshbooks_credentials.sample.yml
+test/fixtures/freshbooks_credentials.yml
 test/fixtures/invoice_create_response.xml
 test/fixtures/invoice_get_response.xml
 test/fixtures/invoice_list_response.xml
+test/fixtures/recurring_create_response.xml
+test/fixtures/recurring_get_response.xml
+test/fixtures/recurring_list_response.xml
 test/fixtures/success_response.xml
+test/live_connection_test.rb
 test/mock_connection.rb
 test/schema/test_definition.rb
 test/schema/test_mixin.rb
@@ -43,3 +62,4 @@ test/test_helper.rb
 test/test_invoice.rb
 test/test_list_proxy.rb
 test/test_page.rb
+test/test_recurring.rb

data/README.md

@@ -0,0 +1,61 @@
+## Home
+
+https://github.com/bcurren/freshbooks.rb
+
+## Todo
+
+Please send me a message if you are interested in contributing. Here is a quick overview of some things I'd like to add to the gem:
+* Merge in forked versions of this gem. (Any idea what forks are worth while?)
+* Provide a way to retrieve the error message with actions beside list are called.
+* Make ListProxy optional on list actions. Some people have valid reason to deal with pagination.
+* Add OAuth.
+* Add WebHooks.
+* More tests, including integration tests.
+* Write some documentation and examples.
+* Launch an official 3.0 (maybe call it 4.0) version of the gem.
+* Post the official version to rubygems.
+* Ensure rubygems aren't required for this gem. 
+
+## About
+
+FreshBooks.rb is a Ruby interface to the FreshBooks API. It exposes easy-to-use classes and methods for interacting with your FreshBooks account.
+
+***NOTE:** These examples are out of date and need to be updated. I will be writing documentation for all the updates soon and will be pushing the changes to rubyforge in the near future.*
+
+## Examples
+
+Initialization:
+
+    FreshBooks::Base.establish_connection('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
+
+## License
+
+This work is distributed under the MIT License. Use/modify the code however you like.
+
+## Download
+
+`sudo gem install bcurren-freshbooks.rb`
+
+## Credits
+
+FreshBooks.rb is written and maintained by [Ben Curren](https://github.com/bcurren) at [Outright.com](http://outright.com/). [Ben Vinegar](http://benv.ca/) was the original developer and we have taken over maintenance of the gem from now on.
+

data/Rakefile

@@ -1,27 +1,22 @@
-%w[rubygems rake rake/clean fileutils newgem rubigen hoe].each { |f| require f }
+%w[rubygems rake rake/clean fileutils rubigen hoe].each { |f| require f }
 require File.dirname(__FILE__) + '/lib/freshbooks'
 
+Hoe.plugin :newgem
+Hoe.plugin :gemcutter
+
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
 $hoe = Hoe.spec('freshbooks.rb') do |p|
-  p.developer('Ben Curren', 'ben@outright.com')
+  p.developer('Ben Curren', 'ben@thecurrens.com')
   p.summary              = ''
   p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  p.rubyforge_name       = p.name # TODO this is default value
-  p.extra_deps           = [ ['activesupport', '>= 0'] ]
+  p.readme_file          = "README.md"
+  p.rubyforge_name       = p.name
+  p.extra_deps           = [ ['activesupport', '>= 3.0.0'] ]
   p.extra_dev_deps = [
     ['newgem', ">= #{::Newgem::VERSION}"],
     ['mocha', ">= 0.9.4"]
   ]
   
   p.clean_globs |= %w[**/.DS_Store tmp *.log]
-  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
-  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
-  p.rsync_args = '-av --delete --ignore-errors'
 end
-
-require 'newgem/tasks' # load /tasks/*.rake
-Dir['tasks/**/*.rake'].each { |t| load t }
-
-# TODO - want other tests/tasks run by default? Add them to the list
-# task :default => [:spec, :features]

data/freshbooks.rb.gemspec

@@ -0,0 +1,43 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "freshbooks.rb"
+  s.version = "3.0.25"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ben Curren"]
+  s.date = "2014-02-13"
+  s.description = ""
+  s.email = ["ben@thecurrens.com"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.md"]
+  s.files = ["History.txt", "LICENSE", "Manifest.txt", "README.md", "Rakefile", "freshbooks.rb.gemspec", "lib/freshbooks.rb", "lib/freshbooks/address.rb", "lib/freshbooks/api.rb", "lib/freshbooks/autobill.rb", "lib/freshbooks/base.rb", "lib/freshbooks/budget.rb", "lib/freshbooks/card.rb", "lib/freshbooks/category.rb", "lib/freshbooks/client.rb", "lib/freshbooks/connection.rb", "lib/freshbooks/contact.rb", "lib/freshbooks/credits.rb", "lib/freshbooks/estimate.rb", "lib/freshbooks/expense.rb", "lib/freshbooks/expiration.rb", "lib/freshbooks/gateway.rb", "lib/freshbooks/gateway_transaction.rb", "lib/freshbooks/invoice.rb", "lib/freshbooks/item.rb", "lib/freshbooks/language.rb", "lib/freshbooks/line.rb", "lib/freshbooks/links.rb", "lib/freshbooks/list_proxy.rb", "lib/freshbooks/payment.rb", "lib/freshbooks/project.rb", "lib/freshbooks/recurring.rb", "lib/freshbooks/response.rb", "lib/freshbooks/schema/definition.rb", "lib/freshbooks/schema/mixin.rb", "lib/freshbooks/staff.rb", "lib/freshbooks/system.rb", "lib/freshbooks/task.rb", "lib/freshbooks/tax.rb", "lib/freshbooks/time_entry.rb", "lib/freshbooks/xml_serializer.rb", "lib/freshbooks/xml_serializer/serializers.rb", "script/console", "script/destroy", "script/generate", "test/fixtures/freshbooks_credentials.sample.yml", "test/fixtures/freshbooks_credentials.yml", "test/fixtures/invoice_create_response.xml", "test/fixtures/invoice_get_response.xml", "test/fixtures/invoice_list_response.xml", "test/fixtures/recurring_create_response.xml", "test/fixtures/recurring_get_response.xml", "test/fixtures/recurring_list_response.xml", "test/fixtures/success_response.xml", "test/live_connection_test.rb", "test/mock_connection.rb", "test/schema/test_definition.rb", "test/schema/test_mixin.rb", "test/test_base.rb", "test/test_connection.rb", "test/test_helper.rb", "test/test_invoice.rb", "test/test_list_proxy.rb", "test/test_page.rb", "test/test_recurring.rb", ".gemtest"]
+  s.homepage = "https://github.com/bcurren/freshbooks.rb"
+  s.licenses = ["MIT"]
+  s.rdoc_options = ["--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "freshbooks.rb"
+  s.rubygems_version = "2.0.14"
+  s.summary = ""
+  s.test_files = ["test/schema/test_definition.rb", "test/schema/test_mixin.rb", "test/test_base.rb", "test/test_connection.rb", "test/test_helper.rb", "test/test_invoice.rb", "test/test_list_proxy.rb", "test/test_page.rb", "test/test_recurring.rb", "test/live_connection_test.rb"]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 3.0.0"])
+      s.add_development_dependency(%q<newgem>, [">= 1.5.3"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9.4"])
+      s.add_development_dependency(%q<hoe>, ["~> 3.9"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 3.0.0"])
+      s.add_dependency(%q<newgem>, [">= 1.5.3"])
+      s.add_dependency(%q<mocha>, [">= 0.9.4"])
+      s.add_dependency(%q<hoe>, ["~> 3.9"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 3.0.0"])
+    s.add_dependency(%q<newgem>, [">= 1.5.3"])
+    s.add_dependency(%q<mocha>, [">= 0.9.4"])
+    s.add_dependency(%q<hoe>, ["~> 3.9"])
+  end
+end

data/lib/freshbooks.rb

@@ -8,15 +8,27 @@ rescue LoadError
   gem 'activesupport'
   require 'active_support'
 end
+require 'active_support/all'
 
 require 'freshbooks/base'
+require 'freshbooks/address'
+require 'freshbooks/api'
+require 'freshbooks/autobill'
+require 'freshbooks/budget'
+require 'freshbooks/card'
 require 'freshbooks/category'
 require 'freshbooks/client'
 require 'freshbooks/connection'
+require 'freshbooks/credits'
 require 'freshbooks/estimate'
 require 'freshbooks/expense'
+require 'freshbooks/expiration'
+require 'freshbooks/gateway'
+require 'freshbooks/gateway_transaction'
 require 'freshbooks/invoice'
+require 'freshbooks/contact'
 require 'freshbooks/item'
+require 'freshbooks/language'
 require 'freshbooks/line'
 require 'freshbooks/links'
 require 'freshbooks/list_proxy'
@@ -25,7 +37,9 @@ require 'freshbooks/project'
 require 'freshbooks/recurring'
 require 'freshbooks/response'
 require 'freshbooks/staff'
+require 'freshbooks/system'
 require 'freshbooks/task'
+require 'freshbooks/tax'
 require 'freshbooks/time_entry'
 
 require 'net/https'
@@ -60,7 +74,7 @@ require 'logger'
 #
 #==============================================================================
 module FreshBooks
-  VERSION = '3.0.18'     # Gem version
+  VERSION = '3.0.25'     # Gem version
   API_VERSION = '2.1' # FreshBooks API version
   SERVICE_URL = "/api/#{API_VERSION}/xml-in"
 
@@ -72,7 +86,7 @@ module FreshBooks
   class ApiAccessNotEnabledError < Error; end;
   class InvalidAccountUrlError < Error; end;
   class AccountDeactivatedError < Error; end;
-  
+
   class ParseError < StandardError
     attr_accessor :original_error, :xml
 

data/lib/freshbooks/address.rb

@@ -0,0 +1,7 @@
+module FreshBooks
+  class Address < FreshBooks::Base
+    define_schema do |s|
+      s.string :street1, :street2, :city, :state, :country, :code
+    end
+  end
+end

data/lib/freshbooks/api.rb

@@ -0,0 +1,7 @@
+module FreshBooks
+  class Api < FreshBooks::Base
+    define_schema do |s|
+      s.fixnum :requests, :request_limit
+    end
+  end
+end

data/lib/freshbooks/autobill.rb

@@ -0,0 +1,9 @@
+module FreshBooks
+  class Autobill < FreshBooks::Base
+
+    define_schema do |s|
+      s.string :gateway_name
+      s.object :card
+    end
+  end
+end

data/lib/freshbooks/base.rb

@@ -4,6 +4,11 @@ require 'freshbooks/xml_serializer'
 module FreshBooks
   class Base
     include FreshBooks::Schema::Mixin
+    attr_reader :error_msg
+    
+    def initialize(args = {})
+      args.each_pair {|k, v| send("#{k}=", v)}
+    end
     
     @@connection = nil
     def self.connection
@@ -15,11 +20,12 @@ module FreshBooks
     end
     
     def self.new_from_xml(xml_root)
-      object = self.new
+      object = self.new()
       
       self.schema_definition.members.each do |member_name, member_options|
-        node = xml_root.elements[member_name]
+        node = xml_root.elements[member_name.dup]
         next if node.nil?
+        next if XmlSerializer.deprecated? node
         
         value = FreshBooks::XmlSerializer.to_value(node, member_options[:type])
         object.send("#{member_name}=", value)
@@ -28,7 +34,10 @@ module FreshBooks
       return object
       
     rescue => e
-      raise ParseError.new(e, xml_root.to_s)
+      error = ParseError.new(e, xml_root.to_s)
+      error.set_backtrace(e.backtrace)
+      raise error
+      # raise ParseError.new(e, xml_root.to_s)
     end
     
     def to_xml(elem_name = nil)
@@ -81,10 +90,15 @@ module FreshBooks
       end
     end
     
-    def self.define_class_method(symbol, &block)
-      self.class.send(:define_method, symbol, &block)
+    def self.metaclass
+      class << self; self; end
     end
     
+    def self.define_class_method(symbol, &block)
+      metaclass.instance_eval do
+        define_method symbol, &block
+      end
+    end
     
     def self.actions(*operations)
       operations.each do |operation|
@@ -145,7 +159,7 @@ module FreshBooks
     
     def api_action(action_name)
       response = FreshBooks::Base.connection.call_api(
-        "#{self.class.api_class_name}.#{action_name}", 
+        "#{self.class.api_class_name}.#{action_name}",
         "#{self.class.api_class_name}_id" => primary_key_value)
       response.success?
     end
@@ -154,15 +168,27 @@ module FreshBooks
       response = FreshBooks::Base.connection.call_api(
         "#{self.class.api_class_name}.#{action_name}",
         self.class.api_class_name => self)
-      self.primary_key_value = response.elements[1].text.to_i if response.success?
-      response.success?
+      if response.success?
+        self.primary_key_value = response.elements[1].text.to_i
+        @error_msg = nil
+        true
+      else
+        @error_msg = response.error_msg
+        false
+      end
     end
     
     def api_update_action(action_name)
       response = FreshBooks::Base.connection.call_api(
         "#{self.class.api_class_name}.#{action_name}",
         self.class.api_class_name => self)
-      response.success?
+      if response.success?
+        @error_msg = nil
+        true
+      else
+        @error_msg = response.error_msg
+        false
+      end
     end
     
   end

data/lib/freshbooks/budget.rb

@@ -0,0 +1,7 @@
+module FreshBooks
+  class Budget < FreshBooks::Base
+    define_schema do |s|
+      s.float :hours
+    end
+  end
+end

data/lib/freshbooks/card.rb

@@ -0,0 +1,9 @@
+module FreshBooks
+  class Card < FreshBooks::Base
+
+    define_schema do |s|
+      s.string :number, :name
+      s.object :expiration
+    end
+  end
+end

data/lib/freshbooks/client.rb

@@ -6,10 +6,13 @@ module FreshBooks
       s.string :mobile, :fax, :notes, :p_street1, :p_street2, :p_city
       s.string :p_state, :p_country, :p_code, :s_street1, :s_street2
       s.string :s_city, :s_state, :s_country, :s_code
+      s.string :language, :currency_code
       s.float :credit, :read_only => true
+      s.object :credits, :read_only => true
       s.date_time :updated, :read_only => true
       s.fixnum :client_id
       s.object :links, :read_only => true
+      s.array :contacts
     end
     
     actions :list, :get, :create, :update, :delete

data/lib/freshbooks/connection.rb

@@ -5,37 +5,46 @@ require 'logger'
 module FreshBooks
   class Connection
     attr_reader :account_url, :auth_token, :utc_offset, :request_headers
-    
+
     @@logger = Logger.new(STDOUT)
     def logger
       @@logger
     end
 
+    def logger=(value)
+      @@logger = value
+    end
+
     def self.log_level=(level)
       @@logger.level = level
     end
     self.log_level = Logger::WARN
-    
+
     def initialize(account_url, auth_token, request_headers = {}, options = {})
-      raise InvalidAccountUrlError.new unless account_url =~ /^[0-9a-zA-Z\-_]+\.freshbooks\.com$/
-      
+      raise InvalidAccountUrlError.new("account_url is expected to be in the form www.example.com without any protocol string or trailing query parameters") unless account_url =~ /^[0-9a-zA-Z\-_]+\.(freshbooks|billingarm)\.com$/
+
       @account_url = account_url
       @auth_token = auth_token
       @request_headers = request_headers
       @utc_offset = options[:utc_offset] || -4
       @start_session_count = 0
     end
-    
+
     def call_api(method, elements = [])
       request = create_request(method, elements)
       result = post(request)
       Response.new(result)
     end
-    
+
+    def direct_post(xml)
+      result = post(xml)
+      Response.new(result)
+    end
+
     def start_session(&block)
       @connection = obtain_connection if @start_session_count == 0
       @start_session_count = @start_session_count + 1
-      
+
       begin
         block.call(@connection)
       ensure
@@ -43,45 +52,45 @@ module FreshBooks
         close if @start_session_count == 0
       end
     end
-    
+
   protected
-    
+
     def create_request(method, elements = [])
       doc = REXML::Document.new '<?xml version="1.0" encoding="UTF-8"?>'
       request = doc.add_element('request')
       request.attributes['method'] = method
-      
+
       elements.each do |element|
         if element.kind_of?(Hash)
           element = element.to_a
         end
         key = element.first
         value = element.last
-        
+
         if value.kind_of?(Base)
           request.add_element(REXML::Document.new(value.to_xml))
         else
           request.add_element(REXML::Element.new(key.to_s)).text = value.to_s
         end
       end
-      
+
       doc.to_s
     end
-    
+
     def obtain_connection(force = false)
       return @connection if @connection && !force
-      
+
       @connection = Net::HTTP.new(@account_url, 443)
       @connection.use_ssl = true
       @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
       @connection.start
     end
-    
+
     def reconnect
       close
       obtain_connection(true)
     end
-    
+
     def close
       begin
         @connection.finish if @connection
@@ -90,7 +99,7 @@ module FreshBooks
       end
       @connection = nil
     end
-    
+
     def post(request_body)
       result = nil
       request = Net::HTTP::Post.new(FreshBooks::SERVICE_URL)
@@ -100,19 +109,19 @@ module FreshBooks
       @request_headers.each_pair do |name, value|
         request[name.to_s] = value
       end
-      
+
       result = post_request(request)
-      
+
       if logger.debug?
         logger.debug "Request:"
         logger.debug request_body
         logger.debug "Response:"
         logger.debug result.body
       end
-      
+
       check_for_api_error(result)
     end
-    
+
     # For connections that take a long time, we catch EOFError's and reconnect seamlessly
     def post_request(request)
       response = nil
@@ -122,7 +131,7 @@ module FreshBooks
           response = connection.request(request)
         rescue EOFError => e
           raise e if has_reconnected
-          
+
           has_reconnected = true
           connection = reconnect
           retry
@@ -130,10 +139,10 @@ module FreshBooks
       end
       response
     end
-    
+
     def check_for_api_error(result)
       return result.body if result.kind_of?(Net::HTTPSuccess)
-      
+
       case result
       when Net::HTTPRedirection
         if result["location"] =~ /loginSearch/
@@ -146,7 +155,7 @@ module FreshBooks
       when Net::HTTPBadRequest
         raise ApiAccessNotEnabledError.new("API not enabled.")
       end
-      
+
       raise InternalError.new("Invalid HTTP code: #{result.class}")
     end
   end