ruby-freshbooks 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Justin Giancola
+
+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/README.md

@@ -0,0 +1,117 @@
+# ruby-freshbooks: a simple FreshBooks API wrapper
+
+This is a Ruby wrapper for the [FreshBooks](http://www.freshbooks.com) API. This style of API wrapper is typically called "reflective". However, because most web APIs (and in particular, FreshBooks' API) do not provide enough metadata to actually be reflective, I feel a more appropriate term is "isomorphic". i.e. the wrapper translates native (in this case Ruby) data structures to and from some representation (in this case XML) that the API understands.
+
+For example,
+
+    conn = FreshBooks::Connection.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+    conn.client.get :client_id => 2
+
+generates the XML:
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <request method="client.get">
+      <client_id>2</client_id>
+    </request>
+
+purely based on the request arguments. This library doesn't actually know anything about the FreshBooks API. Instead it relies on users to read the [FreshBooks API Documentation](http://developers.freshbooks.com/api) and build Ruby data structures (i.e. nested Hash and Array combos) that have isomorphic structure to intended API XML requests. The transformation is quite simple; once you understand how the mapping works any FreshBooks API request can easily be written as a Ruby data structure.
+
+## Detailed Ruby Data Structure to XML Isomorphism Example
+
+The following call will generate and POST the invoice create XML shown in the [FreshBooks API Documentation](http://developers.freshbooks.com/api/view/invoices/):
+
+    conn = FreshBooks::Connection.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+    conn.invoice.create(:invoice => {
+                          :client_id     => 13,
+                          :number        => 'FB00004',
+                          :status        => 'draft',
+                          :date          => '2007-06-23',
+                          :po_number     => 2314,
+                          :discount      => 10,
+                          :notes         => 'Due upon receipt.',
+                          :currency_code => 'CAD',
+                          :terms         => 'Payment due in 30 days.',
+                          :return_uri    => 'http://example.com/account',
+    
+                          :first_name    => 'John',
+                          :last_name     => 'Smith',
+                          :organization  => 'ABC Corp',
+                          :p_street1     => nil,
+                          :p_street2     => nil,
+                          :p_city        => nil,
+                          :p_state       => nil,
+                          :p_country     => nil,
+                          :p_code        => nil,
+                          :vat_name      => nil,
+                          :vat_number    => nil,
+    
+                          :lines => [{ :line => {
+                                         :name         => 'Yard Work',
+                                         :description  => 'Mowed the lawn.',
+                                         :unit_cost    => 10,
+                                         :quantity     => 4,
+                                         :tax1_name    => 'GST',
+                                         :tax2_name    => 'PST',
+                                         :tax1_percent => 5,
+                                         :tax2_percent => 8,
+                                       }}]})
+
+
+## Examples
+
+You can call any `#{namespace}.#{method_name}` method chain against a `FreshBooks::Connection` instance and it will POST a request to the corresponding FreshBooks API method. i.e.
+
+    conn = FreshBooks::Connection.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+    conn.client.get   :client_id => 37
+    conn.invoice.list :client_id => 37, :page => 2, :per_page => 10
+
+## Goals
+
+* easy to use. you can get started using this wrapper in 5 minutes without having to read any documentation
+* flexible enough to support minor changes to the FreshBooks API without requiring a new release. users can simply refer to the official [FreshBooks API Documentation](http://developers.freshbooks.com/api) to see what they can and can't do. you need not depend on this library's maintainer to map/remove new attributes, methods or namespaces as the FreshBooks API changes
+
+## Non-goals
+
+* seamless integration with FreshBooks API via an object interface. i.e.
+
+<pre><code>clients = FreshBooks::Client.list
+client = clients.first
+client.first_name = 'Swenson'
+client.update
+</code></pre>
+
+if you want this sort of thing, please use [freshbooks.rb](http://github.com/bcurren/freshbooks.rb) instead
+
+## Why Shouldn't I use freshbooks.rb Instead?
+
+Maybe you should. It depends on what you want to do. I've used freshbooks.rb before but there were a few things that didn't work for me:
+
+* global connection. I've had the need to connect to multiple FreshBooks accounts within the same program to do things like sync or migrate data. you can't do this with freshbooks.rb because the global connection is owned by `FreshBooks::Base` which is the superclass of `Client`, `Invoice`, etc.
+* requiring a library update every time the FreshBooks API changes. although this doesn't happen very often, it's a little annoying to have to manually patch freshbooks.rb when it does.
+* having to convert everything to and from the business objects the library provides. because the freshbooks.rb API is nice and abstract, it's easy to play around with invoices, clients, etc. as business objects. however, this is less convenient for mass import/export type programs because your data has to be pushed through that object interface instead of just transformed into YAML, CSV, etc. it's also less than desirable when your integration makes use of an alternate model class (i.e. an `ActiveRecord` subclass that you're using to save your FreshBooks data into a database).
+* data transparency. if you're just exploring the FreshBooks API, you might not know all of the attributes that some data types exposes. if you are getting back nicely packaged objects, you'll need to read through the documentation (or source code of freshbooks.rb if you're sure some property ought to be there but isn't and you suspect it's missing from the mapping) to see what you have access to.
+
+## Installation
+
+    gem install ruby-freshbooks
+
+
+## Links
+
+* [FreshBooks API Documentation](http://developers.freshbooks.com/api)
+* [Source Code](http://github.com/elucid/ruby-freshbooks)
+
+## If You Want to Contribute:
+
+1. fork http://github.com/elucid/ruby-freshbooks
+2. make your changes along with specs (don't touch VERSION)
+3. send me a pull request
+
+## TODO
+
+* more examples
+* more documentation
+
+## Copyright
+
+Copyright (c) 2010 Justin Giancola. See LICENSE for details.

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/lib/freshbooks.rb

@@ -0,0 +1,95 @@
+require 'httparty'
+require 'builder'
+
+module FreshBooks
+  API_VERSION = '2.1'
+
+  # provides a Hash-like response object with structure
+  # isomorphic to actual xml response, slightly tidied.
+  class Response < Hash
+    attr_reader :status
+
+    def initialize(data)
+      super nil
+      response = data["response"]
+      response.delete "xmlns"
+      @status = response.delete "status"
+      update response
+    end
+
+    def success?
+      status == "ok"
+    end
+  end
+
+  # FreshBooks API connection. instances are FreshBooks account
+  # specific so you can, e.g. setup two connections and copy/
+  # sync data between them
+  class Connection
+    include HTTParty
+
+    def initialize(domain, token)
+      @domain = domain
+      @auth = { :username => token, :password => 'X' }
+    end
+
+    def api_url                 # :nodoc:
+      "https://#{@domain}/api/#{API_VERSION}/xml-in"
+    end
+
+    # HTTParty (sort of) assumes global connections to services
+    # but we can easily avoid that by making an instance method
+    # that knows account-specific details that calls its
+    # coresponding class method.
+    # note: we only need to provide a #post method because the
+    # FreshBooks API is POST only
+    def post(method, params={}) # :nodoc:
+      Response.new self.class.post(api_url,
+                                   :basic_auth => @auth,
+                                   :body => self.class.xml_body(method, params))
+    end
+
+    # takes nested Hash/Array combos and generates isomorphic
+    # XML bodies to be POSTed to FreshBooks API
+    def self.xml_body(method, params)
+      xml = Builder::XmlMarkup.new
+      xml.tag!("request", :method => method) do
+        build_xml(params, xml)
+      end
+      xml.target!
+    end
+
+    # helper method to xml_body
+    def self.build_xml(obj, target='')
+      xml = Builder::XmlMarkup.new(:target => target)
+      # ZOMG! haven't you ever heard of polymorphism?!?
+      # of course. I'm simply electing not to pollute the
+      # method space of two of the most common Ruby classes.
+      # besides, what are the chances this library will ever
+      # be used in a context where some other library hasn't
+      # already defined #to_xml on Hash...
+      case obj
+      when Hash  : obj.each { |k,v| xml.tag!(k) { build_xml(v, xml) } }
+      when Array : obj.each { |e| build_xml(e ,xml) }
+      else xml.text! obj.to_s
+      end
+      xml.target!
+    end
+
+    # infer API methods based on 2-deep method chains sent to
+    # connections. this allows us to provide a simple interface
+    # without actually knowing anything about the supported API
+    # methods (and hence trusting users to read the official
+    # FreshBooks API documentation)
+    def method_missing(sym, *args) # :nodoc:
+      NamespaceProxy.new self, sym
+    end
+
+    # nothing to see here...
+    class NamespaceProxy < Struct.new(:conn, :namespace) # :nodoc:
+      def method_missing(sym, *args)
+        conn.post "#{namespace}.#{sym}", *args
+      end
+    end
+  end
+end

data/ruby-freshbooks.gemspec

@@ -0,0 +1,35 @@
+Gem::Specification.new do |s|
+  s.name = %q{ruby-freshbooks}
+  s.version = File.read(File.join(File.dirname(__FILE__),'VERSION')).chomp
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Justin Giancola"]
+  s.date = %q{2010-04-25}
+  s.description = %q{simple FreshBooks API wrapper}
+  s.email = %q{elucid@gmail.com}
+  s.files = ["README.md", "LICENSE", "VERSION", "ruby-freshbooks.gemspec", "lib/freshbooks.rb", "spec/freshbooks_spec.rb"]
+  s.has_rdoc = false
+  s.homepage = %q{http://github.com/elucid/ruby-freshbooks}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.4}
+  s.summary = s.description
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0')
+      s.add_runtime_dependency(%q<httparty>, [">= 0.5.0"])
+      s.add_runtime_dependency(%q<builder>, [">= 2.1.2"])
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+    else
+      s.add_dependency(%q<httparty>, [">= 0.5.0"])
+      s.add_dependency(%q<builder>, [">= 2.1.2"])
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    end
+  else
+    s.add_dependency(%q<httparty>, [">= 0.5.0"])
+    s.add_dependency(%q<builder>, [">= 2.1.2"])
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+  end
+end

data/spec/freshbooks_spec.rb

@@ -0,0 +1,56 @@
+require 'freshbooks'
+
+def build_xml(data)
+  FreshBooks::Connection.build_xml data
+end
+
+describe "XML generation:" do
+  describe "simple hash" do
+    it "should serialize correctly" do
+      data = {"foo" => "bar"}
+      build_xml(data).should == "<foo>bar</foo>"
+    end
+  end
+
+  describe "simple hash with Fixnum value" do
+    it "should serialize correctly, coercing to string" do
+      data = {"foo" => 1}
+      build_xml(data).should == "<foo>1</foo>"
+    end
+  end
+
+  describe "simple hash value containing entity" do
+    it "should serialize correctly, escaping entity" do
+      data = {"foo" => "b&r"}
+      build_xml(data).should == "<foo>b&amp;r</foo>"
+    end
+  end
+
+  describe "nested hash" do
+    it "should serialize correctly" do
+      data = {"foo" => {"bar" => "baz"}}
+      build_xml(data).should == "<foo><bar>baz</bar></foo>"
+    end
+  end
+
+  describe "deeply nested hash" do
+    it "should serialize correctly" do
+      data = {"foo" => {"bar" => {"baz" => "bat"}}}
+      build_xml(data).should == "<foo><bar><baz>bat</baz></bar></foo>"
+    end
+  end
+
+  describe "array" do
+    it "should serialize correctly" do
+      data = [{"bar" => "baz"}, {"bar" => "baz"}]
+      build_xml(data).should == "<bar>baz</bar><bar>baz</bar>"
+    end
+  end
+
+  describe "hash with array" do
+    it "should serialize correctly" do
+      data = {"foo" => [{"bar" => "baz"}, {"bar" => "baz"}]}
+      build_xml(data).should == "<foo><bar>baz</bar><bar>baz</bar></foo>"
+    end
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: ruby-freshbooks
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Justin Giancola
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-25 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 0
+        version: 0.5.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: builder
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 1
+        - 2
+        version: 2.1.2
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id003
+description: simple FreshBooks API wrapper
+email: elucid@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- LICENSE
+- VERSION
+- ruby-freshbooks.gemspec
+- lib/freshbooks.rb
+- spec/freshbooks_spec.rb
+has_rdoc: true
+homepage: http://github.com/elucid/ruby-freshbooks
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: simple FreshBooks API wrapper
+test_files: []
+