xero_gateway 2.0.2

data/CHANGELOG.textile

@@ -0,0 +1,51 @@
+h2. Upcoming
+
+* Xero Api version 2.0
+* As get_invoices doesn't download the attached line items, add code to automatically request line items from Xero the first time XeroGateway::Invoice#line_items is accessed. *
+* Populate XeroGateway::Payment class with results from invoice/s including new invoice fields for payment status. *
+
+h2. 1.0.5, released 25/09/2009
+
+* This will be the final release before switching to the Xero API version 2.0
+* Allow multiple tracking options per line item
+
+h2. 1.0.4, released 13/08/2009
+
+* Auto-assign Contact#contact_id and Invoice#invoice_id on creation of either of these records.
+* Add Xero::Gateway#build_contact and Xero::Gateway#build_invoice factory methods to create Contact/Invoice objects associated with the gateway.
+* Add Contact#save method to create/update a contact record based on if it has a contact_id or contact_number.
+* Add Invoice#save method to create (insert only currently supported by Xero API) the invoice.
+* Add #valid? method to each model class to validate it's contents with the minimum required by the API (without calling the API).
+* Add useful API constants throughout the library.
+* Allow Invoice and LineItem to auto-calculate line_amount, sub_total, total_tax and total fields. Existing setters for these fields remain (for backwards compatability) but will be deprecated in the future.
+* Create XeroGateway::AccountList class to make working with the accounts response more powerful and faster (as it caches the last result).
+* Add :updated_after parameter to XeroGateway::Gateway#get_contacts
+* Add XeroGateway::Gateway#update_contacts
+* Add XeroGateway::Gateway#create_invoices
+
+h2. 1.0.3, released 09/12/2008
+
+* Major refactorings to DRY out gateway.rb
+* Removed all messages classes in favour of invoice.to_xml and Invoice.from_xml(element)
+* Added unit tests for the handing of errors from Xero
+
+h2. 1.0.2, released 04/12/2008
+
+* Added implementation of GET /api.xro/1.0/tracking
+
+
+h2. 1.0.1, released 02/12/2008
+
+* Added implementation of GET /api.xro/1.0/accounts
+* Replaced Invoice.id, Contact.id etc with Invoice.invoice_id, Contact.contact_id to avoid Object.id errors
+
+
+h2. 1.0.0, released 01/12/2008
+
+* Initial release, including:
+* PUT /api.xro/1.0/contact
+* GET /api.xro/1.0/contact
+* GET /api.xro/1.0/contacts
+* PUT /api.xro/1.0/invoice
+* GET /api.xro/1.0/invoice
+* GET /api.xro/1.0/invoices

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2008 Tim Connor <tlconnor@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

data/README.textile

@@ -0,0 +1,289 @@
+h1. Xero API wrapper
+
+h2. Introduction
+
+This library is designed to help ruby / rails based applications communicate with the publicly available API for Xero.  If you are unfamiliar with the API, you should first read the documentation, located here "http://blog.xero.com/developer/":http://blog.xero.com/developer/
+
+h2. Usage
+
+<pre><code>    require 'xero_gateway'
+    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+</code></pre>
+
+h2. Authenticating with OAuth
+
+OAuth is built into this library in a very similar manner to the Twitter gem by John Nunemaker ("http://github.com/jnunemaker/twitter":http://github.com/jnunemaker/twitter). So if you've used that before this will all seem familiar.
+
+h3. Consumer Key & Secret
+
+First off, you'll need to get a Consumer Key/Secret pair for your application from Xero. 
+Head to "http://api.xero.com":http://api.xero.com, log in and then click My Applications > Add Application. 
+
+If you want to create a private application (that accesses your own Xero account rather than your users), you'll need to generate an RSA keypair and an X509 certificate.  This can be done with OpenSSL as below:
+<pre><code>    openssl genrsa –out privatekey.pem 1024
+    openssl req –newkey rsa:1024 –x509 –key privatekey.pem –out publickey.cer –days 365
+    openssl pkcs12 –export –out public_privatekey.pfx –inkey privatekey.pem –in publickey.cer
+</code></pre>
+
+On the right-hand-side of your application's page there's a box titled "OAuth Credentials". Use the Key and Secret from this box in order to set up a new Gateway instance.
+
+(If you're unsure about the Callback URL, specify nothing - it will become clear a bit later)
+
+h3. Xero Gateway Initialization
+
+<pre><code>    require 'xero_gateway'
+    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+</code></pre>
+
+or for private applications
+
+<pre><code>    require 'xero_gateway'
+    gateway = XeroGateway::PrivateApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
+</code></pre>
+
+
+h3. Request Token
+
+You'll then need to get a Request Token from Xero.
+
+<pre><code>
+    request_token = gateway.request_token
+</code></pre>
+
+You should keep this around - you'll need it to exchange for an Access Token later. (If you're using Rails, this means storing it in the session or something similar)
+
+Next, you need to redirect your user to the authorisation url for this request token. In Rails, that looks something like this:
+
+<pre><code>
+    redirect_to request_token.authorize_url
+</code></pre>
+
+(Note that Xero doesn't support the OAuth Callback parameter here)
+
+h3. Retrieving an Access Token
+
+If you've specified a Callback URL when setting up your application, your user will be redirected to that URL with an OAuth Verifier as a GET parameter. You can then exchange your Request Token for an Access Token like this (assuming Rails, once again):
+
+<pre><code>
+    gateway.authorize_from_request(request_token.token, request_token.secret, :oauth_verifier => params[:oauth_verifier])
+</code></pre>
+
+(If you haven't specified a Callback URL, the user will be presented with a numeric verifier which they must copy+paste into your application; see examples/oauth.rb for an example)
+
+Now you can access Xero API methods:
+
+<pre><code>
+    gateway.get_contacts
+</code></pre>
+
+h3. Storing Access Tokens
+
+You can also store the Access Token/Secret pair so that you can access the API without user intervention. Currently, these access tokens are only valid for 30 minutes, and will raise a XeroGateway::OAuth::TokenExpired exception if you attempt to access the API beyond the token's expiry time.
+
+<pre><code>
+    access_token, access_secret = gateway.access_token
+</code></pre>
+
+h3. Examples
+
+Open examples/oauth.rb and change CONSUMER_KEY and CONSUMER_SECRET to the values for a Test OAuth Application in order to see an example of OAuth at work.
+
+If you're working with Rails, a controller similar to this might come in handy:
+
+<pre><code>
+  
+  class XeroSessionsController < ApplicationController
+  
+    before_filter :get_xero_gateway
+
+    def new
+      session[:request_token]  = @xero_gateway.request_token.token
+      session[:request_secret] = @xero_gateway.request_token.secret
+
+      redirect_to @xero_gateway.request_token.authorize_url
+    end
+
+    def create
+      @xero_gateway.authorize_from_request(session[:request_token], session[:request_secret],
+                                           :oauth_verifier => params[:oauth_verifier])
+
+      session[:xero_auth] = { :access_token  => @xero_gateway.access_token.token, 
+                              :access_secret => @xero_gateway.access_token.secret }
+
+      session.data.delete(:request_token); session.data.delete(:request_secret)
+    end
+
+    def destroy
+      session.data.delete(:xero_auth)
+    end
+    
+    private
+    
+      def get_xero_gateway
+        @xero_gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+      end
+
+  end
+  
+</code></pre>
+
+Note that I'm just storing the Access Token + Secret in the session here - you could equally store them in the database if you felt like refreshing them every 30 minutes ;)
+
+h2. Implemented interface methods
+
+h3. GET /api.xro/2.0/contact (get_contact_by_id)
+
+Gets a contact record for a specific Xero organisation
+<pre><code>    result = gateway.get_contact_by_id(contact_id)
+    contact = result.contact if result.success?</code></pre>
+
+h3. GET /api.xro/2.0/contact (get_contact_by_number)
+
+Gets a contact record for a specific Xero organisation
+<pre><code>    gateway.get_contact_by_number(contact_number)</code></pre>
+
+
+h3. GET /api.xro/2.0/contacts (get_contacts)
+
+Gets all contact records for a particular Xero customer.
+<pre><code>    gateway.get_contacts(:type => :all, :sort => :name, :direction => :desc)
+    gateway.get_contacts(:type => :all, :updated_after => 1.month.ago) # modified since 1 month ago</code></pre>
+
+
+
+h3. PUT /api.xro/2.0/contact
+
+Saves a contact record for a particular Xero customer.
+<pre><code>    contact = gateway.build_contact
+    contact.name = "The contacts name"
+    contact.email = "whoever@something.com"
+    contact.phone.number = "555 123 4567"
+    contact.address.line_1 = "LINE 1 OF THE ADDRESS"
+    contact.address.line_2 = "LINE 2 OF THE ADDRESS"
+    contact.address.city = "WELLINGTON"
+    contact.address.region = "WELLINGTON"
+    contact.address.country = "NEW ZEALAND"
+    contact.address.post_code = "6021"
+
+    contact.save</code></pre>
+
+
+h3. POST /api.xro/2.0/contact
+
+Updates an existing contact record.
+<pre><code>    contact_retrieved_from_xero.email = "something_new@something.com"
+    contact_retrieved_from_xero.save</code></pre>
+
+
+h3. POST /api.xro/2.0/contacts
+
+Creates a list of contacts or updates them if they have a matching contact_id, contact_number or name.
+This method uses only a single API request to create/update multiple contacts.
+<pre><code>    contacts = [XeroGateway::Contact.new(:name => 'Joe Bloggs'), XeroGateway::Contact.new(:name => 'Jane Doe')]
+    result = gateway.update_contacts(contacts)</code></pre>
+
+
+h3. GET /api.xro/2.0/invoice (get_invoice_by_id)
+
+Gets an invoice record for a specific Xero organisation
+<pre><code>    gateway.get_invoice_by_id(invoice_id)</code></pre>
+
+
+h3. GET /api.xro/2.0/invoice (get_invoice_by_number)
+
+Gets an invoice record for a specific Xero organisation
+<pre><code>    gateway.get_invoice_by_number(invoice_number)</code></pre>
+
+
+
+h3. GET /api.xro/2.0/invoices (get_invoices)
+
+Gets all invoice records for a particular Xero customer.
+<pre><code>    gateway.get_invoices
+    gateway.get_invoices(1.month.ago) # modified since 1 month ago</code></pre>
+
+
+
+h3. PUT /api.xro/2.0/invoice
+
+Inserts an invoice for a specific organization in Xero (Currently only adding new invoices is allowed).
+
+Invoice and line item totals are calculated automatically.
+<pre><code>    invoice = gateway.build_invoice({
+      :invoice_type => "ACCREC",
+      :due_date => 1.month.from_now,
+      :invoice_number => "YOUR INVOICE NUMBER",
+      :reference => "YOUR REFERENCE (NOT NECESSARILY UNIQUE!)",
+      :tax_inclusive => true,
+      :includes_tax => false
+    })
+    invoice.contact.name = "THE NAME OF THE CONTACT"
+    invoice.contact.phone.number = "12345"
+    invoice.contact.address.line_1 = "LINE 1 OF THE ADDRESS"    
+    invoice.add_line_item({
+      :description => "THE DESCRIPTION OF THE LINE ITEM",
+      :unit_amount => 1000,
+      :tax_amount => 125,
+      :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
+      :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
+    })
+	
+		invoice.create</code></pre>
+
+
+h3. PUT /api.xro/2.0/invoices
+
+Inserts multiple invoices for a specific organization in Xero (currently only adding new invoices is allowed).
+This method uses only a single API request to create/update multiple contacts.
+<pre><code>    invoices = [XeroGateway::Invoice.new(...), XeroGateway::Invoice.new(...)]
+    result = gateway.create_invoices(invoices)</code></pre>
+
+h3. GET /api.xro/2.0/accounts
+
+Gets all accounts for a specific organization in Xero.
+<pre><code>    gateway.get_accounts</code></pre>
+
+For more advanced (and cached) access to the accounts list, use the following.
+<pre><code>    accounts_list = gateway.get_accounts_list</code></pre>
+
+Finds account with code of '200'
+<pre><code>    sales_account = accounts_list.find_by_code(200)</code></pre>
+
+Finds all EXPENSE accounts. For a list of valid account types see <code>XeroGateway::Account::TYPE</code>
+<pre><code>   all_expense_accounts = accounts_list.find_all_by_type('EXPENSE')</code></pre>
+
+Finds all accounts with tax_type == 'OUTPUT'. For a list of valid tax types see <code>XeroGateway::Account::TAX_TYPE</code>
+<pre><code>   all_output_tax_accounts = accounts_list.find_all_by_tax_type('OUTPUT')</code></pre>
+
+
+h3. GET /api.xro/2.0/tracking
+
+Gets all tracking categories and their options for a specific organization in Xero.
+<pre><code>    gateway.get_tracking_categories</code></pre>
+
+h3. GET /api.xero/2.0/Organisation
+
+Retrieves organisation details for the authorised application.
+<pre><code>    gateway.get_organisation.organisation</code></pre>
+
+
+h3. GET /api.xero/2.0/Currencies
+
+Retrieves currencies in use for the authorised application.
+<pre><code>    gateway.get_currencies.currencies</code></pre>
+
+
+h3. GET /api.xero/2.0/TaxRates
+
+Retrieves Tax Rates in use for the authorised application.
+<pre><code>    gateway.get_tax_rates.tax_rates</code></pre>
+
+h2. Logging
+
+You can specify a logger to use (so you can track down those tricky exceptions) by using:
+
+<pre>
+  gateway.logger = ActiveSupport::BufferedLogger.new("log_file_name.log")
+</pre>
+
+It doesn't have to be a buffered logger - anything that responds to "info" will do just fine.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the xero gateway.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+

data/examples/oauth.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'pp'
+
+require File.dirname(__FILE__) + '/../lib/xero_gateway.rb'
+
+XERO_CONSUMER_KEY    = "YOUR-OAUTH-CONSUMER-KEY"
+XERO_CONSUMER_SECRET = "YOUR-OAUTH-CONSUMER-SECRET"
+
+gateway = XeroGateway::Gateway.new(XERO_CONSUMER_KEY, XERO_CONSUMER_SECRET)
+
+# authorize in browser
+%x(open #{gateway.request_token.authorize_url})
+
+puts "Enter the verification code from Xero?"
+oauth_verifier = gets.chomp  
+
+gateway.authorize_from_request(gateway.request_token.token, gateway.request_token.secret, :oauth_verifier => oauth_verifier)
+
+puts "Your access token: #{gateway.access_token}"
+puts "(Good for 30 minutes)"
+
+# Example API Call
+pp gateway.get_contacts.contacts
+
+

data/init.rb

@@ -0,0 +1 @@
+require 'xero_gateway'

data/lib/xero_gateway/account.rb

@@ -0,0 +1,78 @@
+module XeroGateway
+  class Account
+    
+    TYPE = {
+      'CURRENT' =>        '',
+      'FIXED' =>          '',
+      'PREPAYMENT' =>     '',
+      'EQUITY' =>         '',
+      'DEPRECIATN' =>     '',
+      'DIRECTCOSTS' =>    '',
+      'EXPENSE' =>        '',
+      'OVERHEADS' =>      '',
+      'CURRLIAB' =>       '',
+      'LIABILITY' =>      '',
+      'TERMLIAB' =>       '',
+      'OTHERINCOME' =>    '',
+      'REVENUE' =>        '',
+      'SALES' =>          ''
+    } unless defined?(TYPE)
+    
+    TAX_TYPE = {
+      'NONE' =>             'No GST',
+      'EXEMPTINPUT' =>      'VAT on expenses exempt from VAT (UK only)',
+      'INPUT' =>            'GST on expenses',
+      'SRINPUT' =>          'VAT on expenses',
+      'ZERORATEDINPUT' =>   'Expense purchased from overseas (UK only)',
+      'RRINPUT' =>          'Reduced rate VAT on expenses (UK Only)', 
+      'EXEMPTOUTPUT' =>     'VAT on sales exempt from VAT (UK only)',
+      'OUTPUT' =>           'OUTPUT',
+      'SROUTPUT' =>         'SROUTPUT',
+      'ZERORATEDOUTPUT' =>  'Sales made from overseas (UK only)',
+      'RROUTPUT' =>         'Reduced rate VAT on sales (UK Only)',
+      'ZERORATED' =>        'Zero-rated supplies/sales from overseas (NZ Only)'
+    } unless defined?(TAX_TYPE)
+    
+    attr_accessor :code, :name, :type, :tax_type, :description
+    
+    def initialize(params = {})
+      params.each do |k,v|
+        self.send("#{k}=", v)
+      end
+    end
+    
+    def ==(other)
+      [:code, :name, :type, :tax_type, :description].each do |field|
+        return false if send(field) != other.send(field)
+      end
+      return true
+    end
+    
+    def to_xml
+      b = Builder::XmlMarkup.new
+      
+      b.Account {
+        b.Code self.code
+        b.Name self.name
+        b.Type self.type
+        b.TaxType self.tax_type
+        b.Description self.description
+      }
+    end
+    
+    def self.from_xml(account_element)
+      account = Account.new
+      account_element.children.each do |element|
+        case(element.name)
+          when "Code" then account.code = element.text
+          when "Name" then account.name = element.text
+          when "Type" then account.type = element.text
+          when "TaxType" then account.tax_type = element.text
+          when "Description" then account.description = element.text
+        end
+      end      
+      account
+    end
+    
+  end
+end