ruby-freshbooks 0.1.2 → 0.2.0

data/CHANGELOG

@@ -0,0 +1,8 @@
+== 0.2.0
+ * added support for OAuth authentication
+
+== 0.1.2
+ * allow users to either require 'ruby-freshbooks' or require 'freshbooks'
+
+== 0.1.1
+ * initial release

data/README.md

@@ -4,8 +4,8 @@ This is a Ruby wrapper for the [FreshBooks](http://www.freshbooks.com) API. This
 
 For example,
 
-    conn = FreshBooks::Connection.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
-    conn.client.get :client_id => 2
+    c = FreshBooks::Client.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+    c.client.get :client_id => 2
 
 generates the XML:
 
@@ -20,8 +20,8 @@ purely based on the request arguments. This library doesn't actually know anythi
 
 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 => {
+    c = FreshBooks::Client.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+    c.invoice.create(:invoice => {
                           :client_id     => 13,
                           :number        => 'FB00004',
                           :status        => 'draft',
@@ -59,11 +59,25 @@ The following call will generate and POST the invoice create XML shown in the [F
 
 ## 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.
+You can call any `#{namespace}.#{method_name}` method chain against a `FreshBooks::Client` instance and it will POST a request with 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
+    c = FreshBooks::Client.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+    c.client.get   :client_id => 37
+    c.invoice.list :client_id => 37, :page => 2, :per_page => 10
+
+## Authentication
+
+You can authenticate using either API tokens or [OAuth](http://oauth.net/). The `FreshBooks::Client.new` constructor will create a client instance of the appropriate type depending on the arguments you pass in. so
+
+    c = FreshBooks::Client.new('youraccount.freshbooks.com', 'yourfreshbooksapitoken')
+
+will return a `FreshBooks::TokenClient` instance, and
+
+    c = FreshBooks::Client.new('youraccount.freshbooks.com', 'your_consumer_key', 'your_consumer_secret', 'your_access_token', 'your_access_token_secret')
+
+will return a `FreshBooks::OAuthClient` instance. both client classes work identically aside from how they authenticate requests.
+
+*note:* this library provides no suppport for obtaining OAuth request or access tokens. for help with that take a look at [FreshBooks' OAuth Documentation](http://developers.freshbooks.com/api/oauth/) and the [oauth gem](http://oauth.rubyforge.org/).
 
 ## Goals
 
@@ -74,10 +88,10 @@ You can call any `#{namespace}.#{method_name}` method chain against a `FreshBook
 
 * 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
+<pre><code>invoices = FreshBooks::Invoice.list
+invoice = invoices.first
+invoice.amount = 500.00
+invoice.update
 </code></pre>
 
 if you want this sort of thing, please use [freshbooks.rb](http://github.com/bcurren/freshbooks.rb) instead
@@ -86,7 +100,7 @@ if you want this sort of thing, please use [freshbooks.rb](http://github.com/bcu
 
 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.
+* 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 `Item`, `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.

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/lib/freshbooks.rb

@@ -1,5 +1,7 @@
 require 'httparty'
 require 'builder'
+require 'openssl'
+require 'cgi'
 
 module FreshBooks
   API_VERSION = '2.1'
@@ -22,15 +24,32 @@ module FreshBooks
     end
   end
 
-  # FreshBooks API connection. instances are FreshBooks account
-  # specific so you can, e.g. setup two connections and copy/
+  class Connection              # :nodoc:
+    # <b>DEPRECATED:</b> Please use <tt>FreshBooks::Client.new</tt> instead.
+    def self.new(*args)
+      warn "[DEPRECATED] `FreshBooks::Connection` is deprecated.  Please use `FreshBooks::Client` instead."
+      Client.new(*args)
+    end
+  end
+
+  # FreshBooks API client. instances are FreshBooks account
+  # specific so you can, e.g. setup two clients and copy/
   # sync data between them
-  class Connection
+  module Client
     include HTTParty
 
-    def initialize(domain, token)
-      @domain = domain
-      @auth = { :username => token, :password => 'X' }
+    # :call-seq:
+    #   new(domain, api_token) => FreshBooks::TokenClient
+    #   new(domain, consumer_key, consumer_secret, token, token_secret) => FreshBooks::OAuthClient
+    #
+    # creates a new FreshBooks API client. returns the appropriate client
+    # type based on the authorization arguments provided
+    def self.new(*args)
+      case args.size
+      when 2 then TokenClient.new(*args)
+      when 5 then OAuthClient.new(*args)
+      else raise ArgumentError
+      end
     end
 
     def api_url                 # :nodoc:
@@ -44,9 +63,9 @@ module FreshBooks
     # 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))
+      Response.new Client.post(api_url,
+                               :headers => auth,
+                               :body => Client.xml_body(method, params))
     end
 
     # takes nested Hash/Array combos and generates isomorphic
@@ -69,15 +88,15 @@ module FreshBooks
       # 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) }
+      when Hash  then obj.each { |k,v| xml.tag!(k) { build_xml(v, xml) } }
+      when Array then 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
+    # clients. 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)
@@ -86,10 +105,68 @@ module FreshBooks
     end
 
     # nothing to see here...
-    class NamespaceProxy < Struct.new(:conn, :namespace) # :nodoc:
+    class NamespaceProxy < Struct.new(:client, :namespace) # :nodoc:
       def method_missing(sym, *args)
-        conn.post "#{namespace}.#{sym}", *args
+        client.post "#{namespace}.#{sym}", *args
       end
     end
   end
+
+  # Basic Auth client. uses an account's API token.
+  class TokenClient
+    include Client
+
+    def initialize(domain, api_token)
+      @domain = domain
+      @username = api_token
+      @password = 'X'
+    end
+
+    def auth
+      { 'Authorization' =>
+        # taken from lib/net/http.rb
+        'Basic ' + ["#{@username}:#{@password}"].pack('m').delete("\r\n") }
+    end
+  end
+
+  # OAuth 1.0 client. access token and secret must be obtained elsewhere.
+  # cf. the {oauth gem}[http://oauth.rubyforge.org/]
+  class OAuthClient
+    include Client
+
+    def initialize(domain, consumer_key, consumer_secret, token, token_secret)
+      @domain          = domain
+      @consumer_key    = consumer_key
+      @consumer_secret = consumer_secret
+      @token           = token
+      @token_secret    = token_secret
+    end
+
+    def auth
+      data = {
+        :realm                  => '',
+        :oauth_version          => '1.0',
+        :oauth_consumer_key     => @consumer_key,
+        :oauth_token            => @token,
+        :oauth_timestamp        => timestamp,
+        :oauth_nonce            => nonce,
+        :oauth_signature_method => 'PLAINTEXT',
+        :oauth_signature        => signature,
+      }.map { |k,v| %Q[#{k}="#{v}"] }.join(',')
+
+      { 'Authorization' => "OAuth #{data}" }
+    end
+
+    def signature
+      CGI.escape("#{@consumer_secret}&#{@token_secret}")
+    end
+
+    def nonce
+      [OpenSSL::Random.random_bytes(10)].pack('m').gsub(/\W/, '')
+    end
+
+    def timestamp
+      Time.now.to_i
+    end
+  end
 end

data/ruby-freshbooks.gemspec

@@ -5,9 +5,9 @@ Gem::Specification.new do |s|
   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.description = %q{simple FreshBooks API wrapper. supports both OAuth and API token authentication}
   s.email = %q{elucid@gmail.com}
-  s.files = ["README.md", "LICENSE", "VERSION", "ruby-freshbooks.gemspec", "lib/freshbooks.rb", "lib/ruby-freshbooks.rb", "spec/freshbooks_spec.rb"]
+  s.files = ["README.md", "LICENSE", "VERSION", "CHANGELOG", "ruby-freshbooks.gemspec", "lib/freshbooks.rb", "lib/ruby-freshbooks.rb", "spec/freshbooks_spec.rb"]
   s.has_rdoc = false
   s.homepage = %q{http://github.com/elucid/ruby-freshbooks}
   s.require_paths = ["lib"]

data/spec/freshbooks_spec.rb

@@ -1,7 +1,7 @@
 require 'freshbooks'
 
 def build_xml(data)
-  FreshBooks::Connection.build_xml data
+  FreshBooks::Client.build_xml data
 end
 
 describe "XML generation:" do
@@ -54,3 +54,10 @@ describe "XML generation:" do
     end
   end
 end
+
+describe "FreshBooks Client instantiation" do
+  it "should create a TokenClient instance when Connection.new is called" do
+    c = FreshBooks::Connection.new('foo.freshbooks.com', 'abcdefghijklm')
+    c.should be_a(FreshBooks::TokenClient)
+  end
+end

metadata

@@ -1,12 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-freshbooks
 version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 2
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Justin Giancola
@@ -19,47 +14,35 @@ default_executable:
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: httparty
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 5
-        - 0
         version: 0.5.0
-  type: :runtime
-  version_requirements: *id001
+    version: 
 - !ruby/object:Gem::Dependency 
   name: builder
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 2
-        - 1
-        - 2
         version: 2.1.2
-  type: :runtime
-  version_requirements: *id002
+    version: 
 - !ruby/object:Gem::Dependency 
   name: rspec
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  type: :development
+  version_requirement: 
+  version_requirements: !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
+    version: 
+description: simple FreshBooks API wrapper. supports both OAuth and API token authentication
 email: elucid@gmail.com
 executables: []
 
@@ -71,6 +54,7 @@ files:
 - README.md
 - LICENSE
 - VERSION
+- CHANGELOG
 - ruby-freshbooks.gemspec
 - lib/freshbooks.rb
 - lib/ruby-freshbooks.rb
@@ -88,23 +72,20 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 0
       version: "0"
+  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 1
-      - 2
       version: "1.2"
+  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: simple FreshBooks API wrapper
+summary: simple FreshBooks API wrapper. supports both OAuth and API token authentication
 test_files: []