xero_gateway 2.1.0 → 2.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: df1d3e6fc6dce9cf79cc5e5c8098f635a50a07d4
+  data.tar.gz: 17287f49b11ab9698ae48b61196afa9445af8598
+SHA512:
+  metadata.gz: fb668a27cc5f55d0e5257387572a8511e80fed505a5b81202ea148ace725ce85c5f2d2d5d45f78fe1cff366d302577ea5440465fd7c1379ced7212351d8aa23a
+  data.tar.gz: 81225482469435edbec27331e3b93fcde586e2605142519714f55c27c4ad13090a0b11632d780ca1b5cde78475d66818135c673cb4fe6b3e2d3a2660b7f2a4d4

data/Gemfile

@@ -1,12 +1,4 @@
-source "http://rubygems.org"
+source 'https://rubygems.org'
 
-gem 'builder', '>= 2.1.2'
-gem 'oauth',   '>= 0.3.6'
-gem 'activesupport'
-
-group :test do
-  gem 'i18n' # For fixing undocumented active_support dependency
-  gem 'mocha'
-  gem 'shoulda'
-  gem 'libxml-ruby'
-end
+# Specify your gem's dependencies in omniauth-mashapeid.gemspec
+gemspec

data/README.md

@@ -0,0 +1,212 @@
+Xero API wrapper [![Build Status](https://travis-ci.org/xero-gateway/xero_gateway.svg?branch=master)](https://travis-ci.org/xero-gateway/xero_gateway) [![Gem Version](https://badge.fury.io/rb/xero_gateway.svg)](https://badge.fury.io/rb/xero_gateway)
+================
+
+# Getting Started
+
+This is a Ruby gem for communicating with the Xero API.
+You can find more information about the Xero API at <https://developer.xero.com>.
+
+## Installation
+
+Just add the `xero_gateway` gem to your Gemfile, like so:
+
+```ruby
+  gem 'xero_gateway'
+```
+
+## Usage
+
+```ruby
+  gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+```
+
+### Authenticating with OAuth
+
+The Xero Gateway uses [OAuth 1.0a](https://oauth.net/core/1.0a/) for authentication. Xero Gateway
+implements OAuth in a very similar manner to the [Twitter gem by John Nunemaker](http://github.com/jnunemaker/twitter)
+, so if you've used that before this will all seem familiar.
+
+  1. **Get a 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>, log in and then click My Applications
+    &gt; 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:
+
+    ```
+      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
+    ```
+
+    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)
+
+  2. **Create a Xero Gateway in your App**
+
+    ```ruby
+      gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+    ```
+
+    or for Private applications
+
+    ```ruby
+      require 'xero_gateway'
+      gateway = XeroGateway::PrivateApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
+    ```
+
+  3. **Creating a Request Token**
+
+    You'll then need to get a Request Token from Xero.
+
+    ```ruby
+      request_token = gateway.request_token
+    ```
+
+    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 authorization url for this
+    request token. In Rails, that looks something like this:
+
+    ```ruby
+      redirect_to request_token.authorize_url
+    ```
+
+    You may also provide a callback parameter, which is the URL within your
+    app the user will be redirected to. See next section for more
+    information on what parameters Xero sends with this request.
+
+    ```ruby
+      request_token = request_token(oauth_callback: "http://yourapp.comcom/xero/callback")
+      redirect_to request_token.authorize_url
+    ```
+
+  4. **Retrieving an Access Token**
+
+    If you've specified a Callback URL when setting up your application or
+    provided an oauth\_callback parameter on your request token, 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):
+
+    ```ruby
+      gateway.authorize_from_request(request_token.token, request_token.secret, oauth_verifier: params[:oauth_verifier])
+    ```
+
+    (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:
+
+    ```ruby
+      gateway.get_contacts
+      # => #<XeroGateway::Response:0x007fd367181388 ...
+    ```
+
+### 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.
+
+```ruby
+  access_token, access_secret = gateway.access_token
+```
+
+You can authorize a `Gateway` instance later on using the
+`authorize_from_access` method:
+
+```ruby
+  gateway = XeroGateway::Gateway.new(XERO_CONSUMER_KEY, XERO_CONSUMER_SECRET)
+  gateway.authorize_from_access(your_stored_token.access_token, your_stored_token.access_secret)
+```
+
+## 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:
+
+```ruby
+  class XeroSessionsController < ApplicationController
+
+    before_action :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
+```
+
+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 ;)
+
+## API Methods
+
+You can find a full listing of all implemented methods on [the wiki page](https://github.com/xero-gateway/xero_gateway/wiki/API-Methods).
+
+## Logging
+
+You can specify a logger to use (so you can track down those tricky
+exceptions) by using:
+
+```ruby
+  gateway.logger = ActiveSupport::BufferedLogger.new("log_file_name.log")
+```
+
+Your logger simply needs to respond to `info`.
+
+## Contributing
+
+We welcome contributions, thanks for pitching in! :sparkles:
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Make sure you have some tests, and they pass! (`bundle exec rake`)
+4. Commit your changes (`git commit -am 'Added some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/Rakefile

@@ -1,6 +1,5 @@
 require 'rake'
 require 'rake/testtask'
-require 'rdoc/task'
 
 desc 'Default: run unit tests.'
 task :default => :test

data/lib/oauth/oauth_consumer.rb

@@ -1,14 +1,30 @@
 module OAuth
   class Consumer
-    
-    def http_with_ssl_client_certificates(*args)
-      @http ||= http_without_ssl_client_certificates(*args).tap do |http|
-        http.cert = options[:ssl_client_cert]
-        http.key  = options[:ssl_client_key]
+
+    if RUBY_VERSION >= "2.0.0"
+
+      # we got Module#prepend, let's use it
+      module ClientCertificateExtensions
+        def http
+          super.tap do |http|
+            http.cert = options[:ssl_client_cert]
+            http.key  = options[:ssl_client_key]
+          end
+        end
       end
+
+      prepend ClientCertificateExtensions
+
+    else
+      def http_with_ssl_client_certificates(*args)
+        @http ||= http_without_ssl_client_certificates(*args).tap do |http|
+          http.cert = options[:ssl_client_cert]
+          http.key  = options[:ssl_client_key]
+        end
+      end
+
+      alias_method_chain :http, :ssl_client_certificates
     end
-  
-    alias_method_chain :http, :ssl_client_certificates
-    
+
   end
-end
+end

data/lib/xero_gateway.rb

@@ -18,10 +18,12 @@ require File.join(File.dirname(__FILE__), 'xero_gateway', 'dates')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'money')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'line_item_calculations')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'response')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'base_record')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'account')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'accounts_list')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'tracking_category')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'contact')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'contact_group')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'line_item')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'payment')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'invoice')
@@ -30,13 +32,15 @@ require File.join(File.dirname(__FILE__), 'xero_gateway', 'credit_note')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'journal_line')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'manual_journal')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'address')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'report')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'phone')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'organisation')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'tax_rate')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'currency')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'item')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'error')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'oauth')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'exceptions')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'gateway')
 require File.join(File.dirname(__FILE__), 'xero_gateway', 'private_app')
-require File.join(File.dirname(__FILE__), 'xero_gateway', 'partner_app')
+require File.join(File.dirname(__FILE__), 'xero_gateway', 'partner_app')

data/lib/xero_gateway/address.rb

@@ -1,44 +1,44 @@
 module XeroGateway
   class Address
-    
+
     ADDRESS_TYPE = {
       'STREET' =>     'Street',
       'POBOX' =>      'PO Box'
     } unless defined?(ADDRESS_TYPE)
-    
+
     # Any errors that occurred when the #valid? method called.
     attr_reader :errors
-    
-    attr_accessor :address_type, :line_1, :line_2, :line_3, :line_4, :city, :region, :post_code, :country
-    
+
+    attr_accessor :address_type, :line_1, :line_2, :line_3, :line_4, :city, :region, :post_code, :country, :attention_to
+
     def initialize(params = {})
       @errors ||= []
-      
+
       params = {
         :address_type => "POBOX"
       }.merge(params)
-      
+
       params.each do |k,v|
         self.send("#{k}=", v)
       end
     end
-    
+
     # Validate the Address record according to what will be valid by the gateway.
     #
-    # Usage: 
+    # Usage:
     #  address.valid?     # Returns true/false
-    #  
+    #
     #  Additionally sets address.errors array to an array of field/error.
     def valid?
       @errors = []
-            
+
       if address_type && !ADDRESS_TYPE[address_type]
         @errors << ['address_type', "must be one of #{ADDRESS_TYPE.keys.join('/')} and is currently #{address_type}"]
       end
-      
+
       @errors.size == 0
-    end    
-    
+    end
+
     def to_xml(b = Builder::XmlMarkup.new)
       b.Address {
         b.AddressType address_type
@@ -50,44 +50,46 @@ module XeroGateway
         b.Region region if region
         b.PostalCode post_code if post_code
         b.Country country if country
+        b.AttentionTo attention_to if attention_to
       }
     end
-    
+
     def self.from_xml(address_element)
       address = Address.new
       address_element.children.each do |element|
         case(element.name)
-          when "AddressType" then address.address_type = element.text
+          when "AddressType"  then address.address_type = element.text
           when "AddressLine1" then address.line_1 = element.text
           when "AddressLine2" then address.line_2 = element.text
           when "AddressLine3" then address.line_3 = element.text
-          when "AddressLine4" then address.line_4 = element.text        
-          when "City" then address.city = element.text
-          when "Region" then address.region = element.text
-          when "PostalCode" then address.post_code = element.text
-          when "Country" then address.country = element.text
+          when "AddressLine4" then address.line_4 = element.text
+          when "City"         then address.city = element.text
+          when "Region"       then address.region = element.text
+          when "PostalCode"   then address.post_code = element.text
+          when "Country"      then address.country = element.text
+          when "AttentionTo"  then address.attention_to = element.text
         end
       end
       address
     end
-    
+
     def self.parse(string)
       address = Address.new
-      
+
       parts = string.split("\r\n")
-      
+
       if(parts.size > 3)
         parts = [parts.shift, parts.shift, parts.shift, parts.join(", ")]
       end
-      
+
       parts.each_with_index do |line, index|
         address.send("line_#{index+1}=", line)
       end
       address
     end
-    
+
     def ==(other)
-      [:address_type, :line_1, :line_2, :line_3, :line_4, :city, :region, :post_code, :country].each do |field|
+      [:address_type, :line_1, :line_2, :line_3, :line_4, :city, :region, :post_code, :country, :attention_to].each do |field|
         return false if send(field) != other.send(field)
       end
       return true

data/lib/xero_gateway/bank_transaction.rb

@@ -25,7 +25,7 @@ module XeroGateway
     attr_accessor :line_items_downloaded
 
     # accessible fields
-    attr_accessor :bank_transaction_id, :type, :date, :reference, :status, :contact, :line_items, :bank_account, :url, :is_reconciled
+    attr_accessor :bank_transaction_id, :type, :date, :reference, :status, :contact, :line_items, :bank_account, :url, :is_reconciled, :updated_at
 
     def initialize(params = {})
       @errors ||= []
@@ -98,6 +98,12 @@ module XeroGateway
       @line_items_downloaded
     end
 
+    %w(sub_total tax_total total).each do |line_item_total_type|
+      define_method("#{line_item_total_type}=") do |new_total|
+        instance_variable_set("@#{line_item_total_type}", new_total) unless line_items_downloaded?
+      end
+    end
+
     # If line items are not downloaded, then attempt a download now (if this record was found to begin with).
     def line_items
       if line_items_downloaded?
@@ -146,6 +152,7 @@ module XeroGateway
       bank_transaction_element.children.each do |element|
         case(element.name)
           when "BankTransactionID" then bank_transaction.bank_transaction_id = element.text
+          when "UpdatedDateUTC" then bank_transaction.updated_at = parse_date_time(element.text)
           when "Type" then bank_transaction.type = element.text
           # when "CurrencyCode" then invoice.currency_code = element.text
           when "Contact" then bank_transaction.contact = Contact.from_xml(element)
@@ -154,8 +161,9 @@ module XeroGateway
           when "Status" then bank_transaction.status = element.text
           when "Reference" then bank_transaction.reference = element.text
           when "LineItems" then element.children.each {|line_item| bank_transaction.line_items_downloaded = true; bank_transaction.line_items << LineItem.from_xml(line_item) }
-          # when "SubTotal" then invoice.sub_total = BigDecimal.new(element.text)
-          # when "TotalTax" then invoice.total_tax = BigDecimal.new(element.text)
+          when "Total" then bank_transaction.total = BigDecimal.new(element.text)
+          when "SubTotal" then bank_transaction.sub_total = BigDecimal.new(element.text)
+          when "TotalTax" then bank_transaction.total_tax = BigDecimal.new(element.text)
           # when "Total" then invoice.total = BigDecimal.new(element.text)
           # when "InvoiceID" then invoice.invoice_id = element.text
           # when "InvoiceNumber" then invoice.invoice_number = element.text