xeroizer 2.20.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7a2ed7ed5abbb823dc78470a4a50e31768592a42
-  data.tar.gz: 828b5d4e36a703a6f6944f3f183964cf59c19ed8
+SHA256:
+  metadata.gz: 1dad6570c636b1273f3569cda927b6c997a1ca6e2cf2ad629cd88c730e57935a
+  data.tar.gz: e4d31e8555ca3a986241f5395cc2f9bba6adaba088a48bf286c552cda7008f40
 SHA512:
-  metadata.gz: f66a004449f5e9570fed2098ebdb4deb1d55aa0c27e8b355e05bb79989d20171e849a45b33118d9ddbdde9908c20ece199e16b3eceff10188e7c71b0a2dc620e
-  data.tar.gz: 6a6a3316543a58ec13f448cbeead6ce143f02a6e8799f0eeb125801e2553da2acb1152cd12797906bf53aa33869ad892ddfdf8f312fbd365838f39e6ad06d787
+  metadata.gz: 3f8bb7c9cbbfd1792285b4c4bd3d73a24100222dc41f86eba5344e5a84b7d1ffd75ef787fbf43a130a2c17d5f8ac16204b518949872bf6107d889d0e14cb2c4c
+  data.tar.gz: bade0622cf61bdff9e444c9ae931c9e8c985c4185c9b0c69c88f285c3869b4df8c83f29294b2087e1b9b045bb2aaa9b171340ab5f63c23d7bae6ac860eb4a769

data/README.md

@@ -1,14 +1,21 @@
-Xeroizer API Library ![Project status](http://stillmaintained.com/waynerobinson/xeroizer.png) [![Build Status](https://travis-ci.org/waynerobinson/xeroizer.svg)](https://travis-ci.org/waynerobinson/xeroizer)
+Xeroizer API Library
 ====================
 
 **Homepage**: 		[http://waynerobinson.github.com/xeroizer](http://waynerobinson.github.com/xeroizer)
+
 **Git**: 					[git://github.com/waynerobinson/xeroizer.git](git://github.com/waynerobinson/xeroizer.git)
+
 **Github**: 			[https://github.com/waynerobinson/xeroizer](https://github.com/waynerobinson/xeroizer)
+
 **Author**: 			Wayne Robinson [http://www.wayne-robinson.com](http://www.wayne-robinson.com)
+
 **Contributors**: See Contributors section below
+
 **Copyright**:    2007-2013
+
 **License**:      MIT License
 
+
 Introduction
 ------------
 
@@ -29,7 +36,7 @@ require 'rubygems'
 require 'xeroizer'
 
 # Create client (used to communicate with the API).
-client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+client = Xeroizer::OAuth2Application.new(YOUR_OAUTH2_CLIENT_ID, YOUR_OAUTH2_CLIENT_SECRET)
 
 # Retrieve list of contacts (note: all communication must be made through the client).
 contacts = client.Contact.all(:order => 'Name')
@@ -38,55 +45,6 @@ contacts = client.Contact.all(:order => 'Name')
 Authentication
 --------------
 
-Xero uses OAuth to authenticate API clients. The OAuth gem (with minor modification) by John Nunemaker ([http://github.com/jnunemaker/twitter](http://github.com/jnunemaker/twitter)) is used in this library. If you've used this before, things will all seem very familar.
-
-There are three methods of authentication detailed below:
-
-### All: Consumer Key/Secret
-
-All methods of authentication require your OAuth consumer key and secret. This can be found for your application
-in the API management console at [http://api.xero.com](http://api.xero.com).
-
-### Public Applications
-
-Public applications use a 3-legged authorisation process. A user will need to authorise your
-application against each organisation that you want access to. Your application can have access
-to many organisations at once by going through the authorisation process for each organisation.
-
-The access token received will expire after 30 minutes. If you want access for longer you will need
-the user to re-authorise your application.
-
-Authentication occurs in 3 steps:
-
-```ruby
-client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
-
-# 1. Get a RequestToken from Xero. :oauth_callback is the URL the user will be redirected to
-#    after they have authenticated your application.
-#
-#    Note: The callback URL's domain must match that listed for your application in http://api.xero.com
-#          otherwise the user will not be redirected and only be shown the authentication code.
-request_token = client.request_token(:oauth_callback => 'http://yourapp.com/oauth/callback')
-
-# 2. Redirect the user to the URL specified by the RequestToken.
-#
-#    Note: example uses redirect_to method defined in Rails controllers.
-redirect_to request_token.authorize_url
-
-# 3. Exchange RequestToken for AccessToken.
-#    This access token will be used for all subsequent requests but it is stored within the client
-#    application so you don't have to record it.
-#
-#    Note: This example assumes the callback URL is a Rails action.
-client.authorize_from_request(request_token.token, request_token.secret, :oauth_verifier => params[:oauth_verifier])
-```
-
-You can now use the client to access the Xero API methods, e.g.
-
-```ruby
-contacts = client.Contact.all
-```
-
 #### Example Rails Controller
 
 ```ruby
@@ -97,25 +55,32 @@ class XeroSessionController < ApplicationController
 	public
 
 		def new
-			request_token = @xero_client.request_token(:oauth_callback => 'http://yourapp.com/xero_session/create')
-			session[:request_token] = request_token.token
-			session[:request_secret] = request_token.secret
-
-			redirect_to request_token.authorize_url
+			url = @xero_client.authorize_url(
+				# The URL's domain must match that listed for your application
+				# otherwise the user will see an invalid redirect_uri error
+				redirect_uri: YOUR_CALLBACK_URL,
+				# space separated, see all scopes at https://developer.xero.com/documentation/oauth2/scopes.
+				# note that `offline_access` is required to get a refresh token, otherwise the access only lasts for 30 mins and cannot be refreshed.
+				scope: "accounting.settings.read offline_access"
+			)
+
+			redirect_to url
 		end
 
 		def create
-			@xero_client.authorize_from_request(
-					session[:request_token],
-					session[:request_secret],
-					:oauth_verifier => params[:oauth_verifier] )
+			token = @xero_client.authorize_from_code(
+				params[:code],
+				redirect_uri: YOUR_CALLBACK_URL
+			)
+
+			connections = @xero_client.current_connections
 
 			session[:xero_auth] = {
-					:access_token => @xero_client.access_token.token,
-					:access_key => @xero_client.access_token.secret }
+				:access_token => token[:access_token],
+				:refresh_token => token[:refresh_token],
+				:tenant_id => connections[1][:tenant_id]
+			}
 
-			session.data.delete(:request_token)
-			session.data.delete(:request_secret)
 		end
 
 		def destroy
@@ -125,150 +90,130 @@ class XeroSessionController < ApplicationController
 	private
 
 		def get_xero_client
-			@xero_client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
+			@xero_client = Xeroizer::OAuth2Application.new(
+				YOUR_OAUTH2_CLIENT_ID,
+				YOUR_OAUTH2_CLIENT_SECRET,
+			)
 
 			# Add AccessToken if authorised previously.
 			if session[:xero_auth]
-				@xero_client.authorize_from_access(
-					session[:xero_auth][:access_token],
-					session[:xero_auth][:access_key] )
+				@xero_client.tenant_id = session[:xero_auth][:tenant_id]
+
+				@xero_client.authorize_from_access(session[:xero_auth][:acesss_token])
 			end
 		end
 end
 ```
 
-#### Storing AccessToken
-
-You can store the access token/secret pair so you can access the API again without user intervention. Currently these
-tokens are only valid for 30 minutes and will raise a `Xeroizer::OAuth::TokenExpired` exception if you try to access
-the API beyond the token's expiry time.
+### OAuth2 Applications
 
-If you want API access for longer consider creating a PartnerApplication which will allow you to renew tokens.
+For more details, checkout Xero's [documentation](https://developer.xero.com/documentation/oauth2/auth-flow)
 
+1. Generate the authorization url and redirect the user to authenticate
 ```ruby
-access_key = client.access_token.token
-access_secret = client.access_token.secret
-```
-
-### Private Applications
-
-Private applications use a 2-legged authorisation process. When you register your application, you will select
-the organisation that is authorised to your application. This cannot be changed afterwards, although you can
-register another private application if you have multiple organisations.
-
-Note: You can only register organisations you are authorised to yourself.
-
-Private applications require a private RSA keypair which is used to sign each request to the API. You can
-generate this keypair on Mac OSX or Linux with OpenSSL. For example:
-
-	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
-
-You need to upload this `public_privatekey.pfx` file to your private application in [http://api.xero.com](http://api.xero.com).
-
-Example usage:
+client = Xeroizer::OAuth2Application.new(
+	YOUR_OAUTH2_CLIENT_ID,
+	YOUR_OAUTH2_CLIENT_SECRET,
+)
+url = client.authorize_url(
+	# The URL's domain must match that listed for your application
+	# otherwise the user will see an invalid redirect_uri error
+	redirect_uri: YOUR_CALLBACK_URL,
+	# space separated, see all scopes at https://developer.xero.com/documentation/oauth2/scopes.
+	# note that `offline_access` is required to get a refresh token, otherwise the access only lasts for 30 mins and cannot be refreshed.
+	scope: "accounting.settings.read offline_access"
+)
 
-```ruby
-client = Xeroizer::PrivateApplication.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET, "/path/to/privatekey.pem")
-contacts = client.Contact.all
+# Rails as an example
+redirect_to url
 ```
 
-To provide a private key directly, set the path to nil and pass in a `private_key` option instead. For example:
+2. In the callback route, use the provided code to retrieve an access token.
 
 ```ruby
-# Using environment variables (e.g. Heroku):
-client = Xeroizer::PrivateApplication.new(key, secret, nil, private_key: ENV["XERO_PRIVATE_KEY"])
+token = client.authorize_from_code(
+	params[:code],
+	redirect_uri: YOUR_CALLBACK_URL
+)
+token.to_hash
+# {
+#   "token_type"=>"Bearer",
+#   "scope"=>"accounting.transactions.read accounting.settings.read",
+#   :access_token=>"...",
+#   :refresh_token=>nil,
+#   :expires_at=>1615220292
+# }
 
-# Using Rails Credentials (Rails 5.2+):
-client = Xeroizer::PrivateApplication.new(key, secret, nil, private_key: Rails.application.credentials.xero_private_key)
+# Save the access_token, refresh_token...
 ```
 
-### Partner Applications
-
-Partner applications use a combination of 3-legged authorisation and private key message signing.
-
-Visit the [https://developer.xero.com/partner/app-partner](Becoming an app partner) page to get permission to create a partner application.
-
-After you have followed the instructions provided by Xero for partner applications and uploaded your certificate you can
-access the partner application in a similar way to public applications.
-
-Authentication occcurs in 3 steps:
-
+3. Retrieve the tenant ids.
 ```ruby
-client = Xeroizer::PartnerApplication.new(
-					YOUR_OAUTH_CONSUMER_KEY,
-					YOUR_OAUTH_CONSUMER_SECRET,
-					"/path/to/privatekey.pem"
-					)
+connections = client.current_connections
+# returns Xeroizer::Connection instances
 
-# 1. Get a RequestToken from Xero. :oauth_callback is the URL the user will be redirected to
-#    after they have authenticated your application.
-#
-#    Note: The callback URL's domain must match that listed for your application in http://api.xero.com
-#          otherwise the user will not be redirected and only be shown the authentication code.
-request_token = client.request_token(:oauth_callback => 'http://yourapp.com/oauth/callback')
+# Save the tenant ids
 
-# 2. Redirect the user to the URL specified by the RequestToken.
-#
-#    Note: example uses redirect_to method defined in Rails controllers.
-redirect_to request_token.authorize_url
-
-# 3. Exchange RequestToken for AccessToken.
-#    This access token will be used for all subsequent requests but it is stored within the client
-#    application so you don't have to record it.
-#
-#    Note: This example assumes the callback URL is a Rails action.
-client.authorize_from_request(request_token.token, request_token.secret, :oauth_verifier => params[:oauth_verifier])
 ```
 
-This AccessToken will last for 30 minutes however, when using the partner application API you can
-renew this token. To be able to renew this token, you need to save the following data from this organisation's
-AccessToken:
-
+4. Use access token and tenant ids to retrieve data.
 ```ruby
-session_handle = client.session_handle
-access_key = client.access_token.token
-access_secret = client.access_token.secret
-```
-
-Two other interesting attributes of the PartnerApplication client are:
+client = Xeroizer::OAuth2Application.new(
+	YOUR_OAUTH2_CLIENT_ID,
+	YOUR_OAUTH2_CLIENT_SECRET,
+	access_token: access_token,
+	tenant_id: tenant_id
+)
+# OR
+client = Xeroizer::OAuth2Application.new(
+	YOUR_OAUTH2_CLIENT_ID,
+	YOUR_OAUTH2_CLIENT_SECRET,
+	tenant_id: tenant_id
+).authorize_from_access(access_token)
 
-> **`#expires_at`**:								Time this AccessToken will expire (usually 30 minutes into the future).
-> **`#authorization_expires_at`**:	How long this organisation has authorised you to access their data (usually 10 years into the future).
+# use the client
+client.Organisation.first
+```
 
 #### AccessToken Renewal
-
-Renewal of an access token requires knowledge of the previous access token generated for this organisation. To renew:
+Renewal of an access token requires the refresh token generated for this organisation. To renew:
 
 ```ruby
-# If you still have a client instance.
-client.renew_access_token
+client = Xeroizer::OAuth2Application.new(
+	YOUR_OAUTH2_CLIENT_ID,
+	YOUR_OAUTH2_CLIENT_SECRET,
+	access_token: access_token,
+	refresh_token: refresh_token,
+	tenant_id: tenant_id
+)
 
-# If you are renewing from stored token/session details.
-client.renew_access_token(access_token, access_secret, session_handle)
+client.renew_access_token
 ```
+If you lose these details at any stage you can always reauthorise by redirecting the user back to the Xero OAuth gateway.
 
-This will invalidate the previous token and refresh the `access_key` and `access_secret` as specified in the
-initial authorisation process. You must always know the previous token's details to renew access to this
-session.
+#### Custom Connections
+Custom Connections are a paid-for option for private M2M applications. The generated token expires and needs recreating if expired. 
 
-If you lose these details at any stage you can always reauthorise by redirecting the user back to the Xero OAuth gateway.
+```ruby
+client = Xeroizer::OAuth2Application.new(
+	YOUR_OAUTH2_CLIENT_ID,
+	YOUR_OAUTH2_CLIENT_SECRET
+)
 
-#### Branding Themes API
+token = client.authorize_from_client_credentials
+```
+You can check the status of the token with the `expires?` and `expired?` methods.
 
-Once you are approved as a Xero Partner you can request unofficial documentation to do with customizing Payment Services and Branding Themes using the API. There is more info on that [here](  https://github.com/waynerobinson/xeroizer/pull/439).
 
 Retrieving Data
 ---------------
 
 Each of the below record types is implemented within this library. To allow for multiple access tokens to be used at the same
-time in a single application, the model classes are accessed from the instance of PublicApplication, PrivateApplication
-or PartnerApplication. All class-level operations occur on this singleton. For example:
+time in a single application, the model classes are accessed from the instance of OAuth2Application. All class-level operations occur on this singleton. For example:
 
 ```ruby
-xero = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY, YOUR_OAUTH_CONSUMER_SECRET)
-xero.authorize_from_access(session[:xero_auth][:access_token], session[:xero_auth][:access_key])
+xero = Xeroizer::OAuth2Application.new(YOUR_OAUTH2_CLIENT_ID, YOUR_OAUTH2_CLIENT_SECRET, tenant_id: tenant_id)
+xero.authorize_from_access(session[:xero_auth][:access_token])
 
 contacts = xero.Contact.all(:order => 'Name')
 
@@ -648,8 +593,8 @@ You can set this option when initializing an application:
 
 ```ruby
 # Sleep for 2 seconds every time the rate limit is exceeded.
-client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
-                                         YOUR_OAUTH_CONSUMER_SECRET,
+client = Xeroizer::OAuth2Application.new(YOUR_OAUTH2_CLIENT_ID,
+                                         YOUR_OAUTH2_CLIENT_SECRET,
                                          :rate_limit_sleep => 2)
 ```
 
@@ -666,8 +611,8 @@ You can set this option when initializing an application:
 
 ```ruby
 # Sleep for 1 second and retry up to 3 times when Xero claims the nonce was used.
-client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
-                                         YOUR_OAUTH_CONSUMER_SECRET,
+client = Xeroizer::OAuth2Application.new(YOUR_OAUTH2_CLIENT_ID,
+                                         YOUR_OAUTH2_CLIENT_SECRET,
                                          :nonce_used_max_attempts => 3)
 ```
 
@@ -679,8 +624,8 @@ You can add an optional parameter to the Xeroizer Application initialization, to
 
 ```ruby
 XeroLogger = Logger.new('log/xero.log', 'weekly')
-client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
-                                         YOUR_OAUTH_CONSUMER_SECRET,
+client = Xeroizer::OAuth2Application.new(YOUR_OAUTH2_CLIENT_ID,
+                                         YOUR_OAUTH2_CLIENT_SECRET,
                                          :logger => XeroLogger)
 ```
 
@@ -692,7 +637,7 @@ time Xeroizer makes an HTTP request, which is potentially useful for both
 throttling and logging:
 
 ```ruby
-Xeroizer::PublicApplication.new(
+Xeroizer::OAuth2Application.new(
   credentials[:key], credentials[:secret],
   before_request: ->(request) { puts "Hitting this URL: #{request.url}" },
   after_request: ->(request, response) { puts "Got this response: #{response.code}" },
@@ -711,8 +656,8 @@ By default, the API accepts unit prices (UnitAmount) to two decimals places. If
 
 
 ```ruby
-client = Xeroizer::PublicApplication.new(YOUR_OAUTH_CONSUMER_KEY,
-                                         YOUR_OAUTH_CONSUMER_SECRET,
+client = Xeroizer::OAuth2Application.new(YOUR_OAUTH2_CLIENT_ID,
+                                         YOUR_OAUTH2_CLIENT_SECRET,
                                          :unitdp => 4)
 ```
 
@@ -721,23 +666,19 @@ This option adds the unitdp=4 query string parameter to all requests for models
 Tests
 -----
 
-The tests within the repository can be run by setting up a [Private App](https://developer.xero.com/documentation/auth-and-limits/private-applications).  You can create a Private App in the [developer portal](https://developer.xero.com/myapps/), it's suggested that you create it against the [Demo Company (AU)](https://developer.xero.com/documentation/getting-started/development-accounts). Demo Company expires after 28 days, so you will need to reset it and create a new Private App if you Demo Company has expired. Make sure you create the Demo Company in Australia region.
-
-Once you have created your Private App, set these environment variables:
-```
-EXPORT CONSUMER_KEY="your private app's consumer key"
-EXPORT CONSUMER_SECRET="your private app's consumer secret"
-EXPORT PRIVATE_KEY_PATH="the path to your private app's private key"
-```
+OAuth2 Tests
 
-PRIVATE_KEY_PATH is the path to the private key for your Private App (you uploaded the Public Key when you created the Private App)
+The tests within the repository can be run by setting up a [OAuth2 App](https://developer.xero.com/documentation/guides/oauth2/auth-flow/).  You can create a Private App in the [developer portal](https://developer.xero.com/myapps/), it's suggested that you create it against the [Demo Company (AU)](https://developer.xero.com/documentation/getting-started/development-accounts). Demo Company expires after 28 days, so you will need to reset it and re-connect to it if your Demo Company has expired. Make sure you create the Demo Company in Australia region.
 
-Then run the tests
 ```
+export XERO_CLIENT_ID="asd"
+export XERO_CLIENT_SECRET="asdfg"
+export XERO_ACCESS_TOKEN="sadfsdf"
+export XERO_TENANT_ID="asdfasdfasdfasd"
+
 rake test
 ```
 
-
 ### Contributors
 Xeroizer was inspired by the https://github.com/tlconnor/xero_gateway gem created by Tim Connor
 and Nik Wakelin and portions of the networking and authentication code are based completely off

data/lib/xeroizer/connection.rb

@@ -0,0 +1,49 @@
+module Xeroizer
+  class Connection
+    attr_accessor :attributes
+    attr_reader :parent
+
+    class << self
+      def current_connections(client)
+        response = do_request(client)
+
+        if response.success?
+          JSON.parse(response.plain_body).map do |connection_json|
+            build(connection_json, client)
+          end
+        else
+          raise Xeroizer::OAuth::TokenInvalid, response.plain_body
+        end
+      end
+
+      def build(attributes, parent)
+        record = new(parent)
+        record.attributes = attributes
+        record
+      end
+
+      private
+
+      def do_request(client)
+        client.get('https://api.xero.com/connections')
+      end
+    end
+
+    def initialize(parent)
+      @parent = parent
+      @attributes = {}
+    end
+
+    def method_missing(name, *_args)
+      @attributes.send(:[], name.to_s.camelcase(:lower))
+    end
+
+    def delete
+      parent.delete("https://api.xero.com/connections/#{id}")
+    end
+
+    def to_h
+      attributes.transform_keys(&:underscore)
+    end
+  end
+end

data/lib/xeroizer/exceptions.rb

@@ -155,5 +155,7 @@ module Xeroizer
     end
 
   end
+
+  class InvalidClientError < XeroizerError; end
   
 end

data/lib/xeroizer/generic_application.rb

@@ -6,9 +6,11 @@ module Xeroizer
     include Http
     extend Record::ApplicationHelper
 
-    attr_reader :client, :xero_url, :logger, :rate_limit_sleep, :rate_limit_max_attempts,
+    attr_reader :client, :logger, :rate_limit_sleep, :rate_limit_max_attempts,
                 :default_headers, :unitdp, :before_request, :after_request, :around_request, :nonce_used_max_attempts
 
+    attr_accessor :xero_url
+
     extend Forwardable
     def_delegators :client, :access_token
 
@@ -26,6 +28,7 @@ module Xeroizer
     record :ExpenseClaim
     record :Invoice
     record :InvoiceReminder
+    record :HistoryRecord
     record :OnlineInvoice
     record :Item
     record :Journal
@@ -37,6 +40,7 @@ module Xeroizer
     record :Prepayment
     record :Overpayment
     record :PurchaseOrder
+    record :Quote
     record :Receipt
     record :RepeatingInvoice
     record :Schedule
@@ -63,7 +67,8 @@ module Xeroizer
       # @see PublicApplication
       # @see PrivateApplication
       # @see PartnerApplication
-      def initialize(consumer_key, consumer_secret, options = {})
+      def initialize(client, options = {})
+        raise Xeroizer::InvalidClientError.new unless [OAuth, OAuth2].member?(client.class)
         @xero_url = options[:xero_url] || "https://api.xero.com/api.xro/2.0"
         @rate_limit_sleep = options[:rate_limit_sleep] || false
         @rate_limit_max_attempts = options[:rate_limit_max_attempts] || 5
@@ -72,7 +77,7 @@ module Xeroizer
         @before_request = options.delete(:before_request)
         @after_request = options.delete(:after_request)
         @around_request = options.delete(:around_request)
-        @client = OAuth.new(consumer_key, consumer_secret, options.merge({default_headers: default_headers}))
+        @client = client
         @logger = options[:logger] || false
         @unitdp = options[:unitdp] || 2
       end