xero_gateway 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df1d3e6fc6dce9cf79cc5e5c8098f635a50a07d4
-  data.tar.gz: 17287f49b11ab9698ae48b61196afa9445af8598
+  metadata.gz: 7df3847b8dad3d3d5c593510c72696d7a39763b3
+  data.tar.gz: 5427008d5f2f9d14dfa3834a7125ad84af3db90c
 SHA512:
-  metadata.gz: fb668a27cc5f55d0e5257387572a8511e80fed505a5b81202ea148ace725ce85c5f2d2d5d45f78fe1cff366d302577ea5440465fd7c1379ced7212351d8aa23a
-  data.tar.gz: 81225482469435edbec27331e3b93fcde586e2605142519714f55c27c4ad13090a0b11632d780ca1b5cde78475d66818135c673cb4fe6b3e2d3a2660b7f2a4d4
+  metadata.gz: 0fd76a237a99430e26b722736025353481263717be0cc0428e1c50180c6106c11b856f9aae2ea5af5452ebaf519f534f4d8e9638ac59a51b2c1cb8322ff66c73
+  data.tar.gz: 874d4febc34ac826a6df223246c453ae8c74bdf35ecbdffd84d3d6a2ebd94f8d48d9358f8015a5a60118635558303c30ace9868e5732e996c83c48ac5d995ebc

data/README.md

@@ -26,120 +26,126 @@ The Xero Gateway uses [OAuth 1.0a](https://oauth.net/core/1.0a/) for authenticat
 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.
+### Authenticating: Public/Partner Applications
 
-    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:
+Public (or Partner, if you've been through the process to be approved) are traditional three-legged OAuth apps that can be used to access many different Xero accounts.
 
-    ```
-      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
-    ```
+  1. **Get a Consumer Key & Secret**
 
-    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.
+  First off, you'll need to get a Consumer Key/Secret pair for your application from Xero.
 
-    (If you're unsure about the Callback URL, specify nothing - it will
-    become clear a bit later)
+  Head to <https://api.xero.com>, log in and then click My Applications &gt; Add Application.
 
-  2. **Create a Xero Gateway in your App**
+  Part of the process for this will ask you for an "OAuth Redirect URL". This is where customers will be redirected once they complete logging in with Xero.
 
-    ```ruby
-      gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
-    ```
+  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.
 
-    or for Private applications
+  2. **Create a Xero Gateway in your App**
 
-    ```ruby
-      require 'xero_gateway'
-      gateway = XeroGateway::PrivateApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
-    ```
+  ```ruby
+    gateway = XeroGateway::Gateway.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+  ```
 
   3. **Creating a Request Token**
 
-    You'll then need to get a Request Token from Xero.
+  You'll then need to get a Request Token from Xero.
 
-    ```ruby
-      request_token = gateway.request_token
-    ```
+  ```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)
+  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:
+  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
-    ```
+  ```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.
+  You may also provide a callback parameter, which is the URL within your app the user will be redirected to. You need to ensure that the domain and port match the callback URL you specified in the Xero Developer Center!
 
-    ```ruby
-      request_token = request_token(oauth_callback: "http://yourapp.comcom/xero/callback")
-      redirect_to request_token.authorize_url
-    ```
+  ```ruby
+    request_token = request_token(oauth_callback: "https://yourapp.com/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):
+  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])
-    ```
+  ```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)
+  (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:
+  Now you can access Xero API methods:
 
-    ```ruby
-      gateway.get_contacts
-      # => #<XeroGateway::Response:0x007fd367181388 ...
-    ```
+  ```ruby
+    gateway.get_contacts
+    # => #<XeroGateway::Response:0x007fd367181388 ...
+  ```
 
-### Storing Access Tokens
+  #### 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.
+  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
-```
+  ```ruby
+    access_token, access_secret = gateway.access_token
+  ```
 
-You can authorize a `Gateway` instance later on using the
-`authorize_from_access` method:
+  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)
-```
+  ```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)
+  ```
+
+ ### Authenticating: Private Applications
+
+Private applications are used to access a single Xero account.
+
+1. **Get a Consumer Key & Secret**
+
+  Head to <https://api.xero.com>, log in and then click My Applications &gt; Add Application.
+
+  You'll need to generate an RSA keypair and an X509 certificate. This can be done with OpenSSL as below:
+
+  ```bash
+    openssl genrsa -out privatekey.pem
+    openssl req -newkey rsa:1024 -x509 -days 365 -in privatekey.pem -out publickey.cer
+  ```
+
+  You can then copy `publickey.cer` and paste it into the certificate box (`cat publickey.cer | pbcopy` on a Mac :apple:)
+
+  Make sure you keep `privatekey.pem` about, as you'll need it to connect to Xero in your app.
+
+2. **Create a Xero Gateway in your App**
+
+  It's as easy as:
+
+  ```ruby
+    require 'xero_gateway'
+    gateway = XeroGateway::PrivateApp.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, PATH_TO_YOUR_PRIVATE_KEY)
+
+    pp gateway.get_contacts
+  ```
+
+  Note that for private apps, your consumer key and secret do double duty as your access token and secret pair :)
 
 ## 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
+Open `examples/oauth.rb` and change `CONSUMER_KEY` and `CONSUMER_SECRET` to
+the values for a Test OAuth Public Application in order to see an example of
 OAuth at work.
 
+There's also `examples/private_app.rb` if you'd like to see an example private app.
+
 If you're working with Rails, a controller similar to this might come in
 handy:
 
@@ -179,8 +185,7 @@ handy:
   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
+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

data/examples/partner_app.rb

@@ -6,13 +6,9 @@ require File.dirname(__FILE__) + '/../lib/xero_gateway.rb'
 XERO_CONSUMER_KEY    = "YOUR CONSUMER KEY"
 XERO_CONSUMER_SECRET = "YOUR CONSUMER SERET"
 
-ENTRUST_CERT_NAME    = "YOUR_ENTRUST_CERT.pem"
-ENTRUST_KEY_NAME     = "YOUR_ENTRUST_KEY.pem"
 PRIVATE_KEY          = "YOUR_PRIVATE_KEY.pem"
 
 gateway = XeroGateway::PartnerApp.new(XERO_CONSUMER_KEY, XERO_CONSUMER_SECRET, 
-                                      :ssl_client_cert  => File.join(File.dirname(__FILE__), ENTRUST_CERT_NAME)
-                                      :ssl_client_key   => File.join(File.dirname(__FILE__), ENTRUST_KEY_NAME),
                                       :private_key_file => File.join(File.dirname(__FILE__), PRIVATE_KEY))
 
 # authorize in browser

data/examples/private_app.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'pp'
+
+require_relative '../lib/xero_gateway.rb'
+
+XERO_CONSUMER_KEY    = "YOUR CONSUMER KEY"
+XERO_CONSUMER_SECRET = "YOUR CONSUMER SECRET"
+PATH_TO_PRIVATE_KEY  = "/path/to/privatekey.pem"
+
+gateway = XeroGateway::PrivateApp.new(
+  XERO_CONSUMER_KEY,
+  XERO_CONSUMER_SECRET,
+  PATH_TO_PRIVATE_KEY)
+
+# Example API Call
+pp gateway.get_contacts.contacts
+
+

data/lib/xero_gateway/account.rb

@@ -1,6 +1,6 @@
 module XeroGateway
   class Account
-    
+
     TYPE = {
       'CURRENT' =>        '',
       'FIXED' =>          '',
@@ -17,14 +17,27 @@ module XeroGateway
       'REVENUE' =>        '',
       'SALES' =>          ''
     } unless defined?(TYPE)
-    
+
+    ACCOUNT_CLASS = {
+      'ASSET'     => '',
+      'EQUITY'    => '',
+      'EXPENSE'   => '',
+      'LIABILITY' => '',
+      'REVENUE'   => '',
+    } unless defined?(ACCOUNT_CLASS)
+
+    STATUSES = {
+      'ACTIVE'   => '',
+      'ARCHIVED' => '',
+    } unless defined?(STATUSES)
+
     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)', 
+      'RRINPUT' =>          'Reduced rate VAT on expenses (UK Only)',
       'EXEMPTOUTPUT' =>     'VAT on sales exempt from VAT (UK only)',
       'ECZROUTPUT' =>       'EC Zero-rated output',
       'OUTPUT' =>           'OUTPUT (old rate)',
@@ -34,28 +47,30 @@ module XeroGateway
       'RROUTPUT' =>         'Reduced rate VAT on sales (UK Only)',
       'ZERORATED' =>        'Zero-rated supplies/sales from overseas (NZ Only)'
     } unless defined?(TAX_TYPE)
-    
-    attr_accessor :account_id, :code, :name, :type, :tax_type, :description, :system_account, :enable_payments_to_account, :currency_code
-    
+
+    attr_accessor :account_id, :code, :name, :type, :status, :account_class, :tax_type, :description, :system_account, :enable_payments_to_account, :currency_code
+
     def initialize(params = {})
       params.each do |k,v|
         self.send("#{k}=", v)
       end
     end
-    
+
     def ==(other)
-      [:account_id, :code, :name, :type, :tax_type, :description, :system_account, :enable_payments_to_account].each do |field|
+      [:account_id, :code, :name, :type, :status, :account_class, :tax_type, :description, :system_account, :enable_payments_to_account].each do |field|
         return false if send(field) != other.send(field)
       end
       return true
     end
-    
+
     def to_xml(b = Builder::XmlMarkup.new, options={})
       b.tag!(options[:name] ? options[:name] : 'Account') {
         b.AccountID self.account_id
         b.Code self.code
         b.Name self.name
         b.Type self.type
+        b.Status self.status
+        b.Class self.account_class
         b.TaxType self.tax_type
         b.Description self.description
         b.SystemAccount self.system_account unless self.system_account.nil?
@@ -63,7 +78,7 @@ module XeroGateway
         b.CurrencyCode currency_code if currency_code
       }
     end
-    
+
     def self.from_xml(account_element)
       account = Account.new
       account_element.children.each do |element|
@@ -72,15 +87,17 @@ module XeroGateway
           when "Code" then account.code = element.text
           when "Name" then account.name = element.text
           when "Type" then account.type = element.text
+          when "Status" then account.status = element.text
+          when "Class" then account.account_class = element.text
           when "TaxType" then account.tax_type = element.text
           when "Description" then account.description = element.text
           when "SystemAccount" then account.system_account = element.text
           when "EnablePaymentsToAccount" then account.enable_payments_to_account = (element.text == 'true')
           when "CurrencyCode" then account.currency_code = element.text
         end
-      end      
+      end
       account
     end
-    
+
   end
 end

data/lib/xero_gateway/bank_transaction.rb

@@ -25,7 +25,8 @@ 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, :updated_at
+    attr_writer   :line_items
+    attr_accessor :bank_transaction_id, :type, :date, :reference, :status, :contact, :bank_account, :url, :is_reconciled, :updated_at, :currency_code, :currency_rate
 
     def initialize(params = {})
       @errors ||= []
@@ -131,7 +132,8 @@ module XeroGateway
       b.BankTransaction {
         b.BankTransactionID bank_transaction_id if bank_transaction_id
         b.Type type
-        # b.CurrencyCode self.currency_code if self.currency_code
+        b.CurrencyCode currency_code if currency_code
+        b.CurrencyRate currency_rate if currency_rate
         contact.to_xml(b) if contact
         bank_account.to_xml(b, :name => 'BankAccount') if bank_account
         b.Date BankTransaction.format_date(date || Date.today)
@@ -154,7 +156,8 @@ module XeroGateway
           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 "CurrencyCode" then bank_transaction.currency_code = element.text
+          when "CurrencyRate" then bank_transaction.currency_rate = BigDecimal.new(element.text)
           when "Contact" then bank_transaction.contact = Contact.from_xml(element)
           when "BankAccount" then bank_transaction.bank_account = Account.from_xml(element)
           when "Date" then bank_transaction.date = parse_date(element.text)
@@ -164,14 +167,6 @@ module XeroGateway
           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
-          # when "Payments" then element.children.each { | payment | invoice.payments << Payment.from_xml(payment) }
-          # when "AmountDue" then invoice.amount_due = BigDecimal.new(element.text)
-          # when "AmountPaid" then invoice.amount_paid = BigDecimal.new(element.text)
-          # when "AmountCredited" then invoice.amount_credited = BigDecimal.new(element.text)
-          # when "SentToContact" then invoice.sent_to_contact = (element.text.strip.downcase == "true")
           when "IsReconciled" then bank_transaction.is_reconciled = (element.text.strip.downcase == "true")
           when "Url" then bank_transaction.url = element.text
         end

data/lib/xero_gateway/base_record.rb

@@ -1,5 +1,8 @@
 module XeroGateway
   class BaseRecord
+
+    class UnsupportedAttributeType < StandardError; end
+
     class_attribute :element_name
     class_attribute :attribute_definitions
 
@@ -59,27 +62,35 @@ module XeroGateway
       if Hash === attr_definition
         element.children.each do |child|
           next unless child.respond_to?(:name)
-          
+
           child_attribute = child.name
           child_attr_definition = attr_definition[child_attribute]
+          child_attr_name       = "#{attribute}#{child_attribute}" # SalesDetails/UnitPrice => SalesDetailsUnitPrice
+
           next unless child_attr_definition
 
-          from_xml_attributes(child, "#{attribute}#{child_attribute}", child_attr_definition)
+          from_xml_attributes(child, child_attr_name, child_attr_definition)
         end
 
         return
       end
 
       value = case attr_definition
-        when :boolean then  element.text == "true"
-        when :float   then  element.text.to_f
-        when :integer then  element.text.to_i
-        else                element.text
-      end if element.text.present?
+        when :boolean  then  element.text == "true"
+        when :float    then  element.text.to_f
+        when :integer  then  element.text.to_i
+        when Array     then  array_from_xml(element, attr_definition)
+        else                 element.text
+      end if element.text.present? || element.children.present?
 
       send("#{attribute.underscore}=", value)
     end
 
+    def array_from_xml(element, attr_definition)
+      definition_klass = attr_definition.first
+      element.children.map { |child_el| definition_klass.from_xml(child_el) }
+    end
+
     def to_xml_attributes(builder = Builder::XmlMarkup.new, path = nil, attr_definitions = self.class.attribute_definitions)
       attr_definitions.each do |attr, value|
         case value
@@ -87,6 +98,14 @@ module XeroGateway
           builder.__send__(attr) do
             to_xml_attributes(builder, "#{path}#{attr}", value)
           end
+        when Array
+          raise UnsupportedAttributeType.new("#{value} instances don't respond to #to_xml") unless value.first.method_defined?(:to_xml)
+          value = send("#{path}#{attr}".underscore) || []
+          builder.__send__(attr) do |array_wrapper|
+            value.map do |k|
+              k.to_xml(array_wrapper)
+            end
+          end
         else
           builder.__send__(attr, send("#{path}#{attr}".underscore))
         end