xero-ruby 2.0.2 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 333abb6f3c4cb576451f3fa4f47be4843502e06acb09be2a918ec2f2f313b4c2
-  data.tar.gz: adba7b3e9fac9cd66ea70935598c08fcc3506221fb27219200686d9630a2b3ce
+  metadata.gz: c8250dd8ab9c60af3fa465ae94075ab3f9a6ca740ba550ca1c89ce06e7d2d293
+  data.tar.gz: 34d4b08070f17257e204ba7072c0f294fa9424b0a8cb230326d6b678264320a4
 SHA512:
-  metadata.gz: 4a07d78ad0a2f8c3be6f2ee677342a85dfc862b075095820cc193a572329218ad0bc055d0a1d2fe9484e7cf208056dfd55040b2f1b6dd6b6600589caee3253d5
-  data.tar.gz: a7578f993ff86feaa3ef0d221188a64210f5b8ceec35e0fbdb7749424532c8f83a49cfdb9f76cb5b0e832f5d526b9b063a1413743752632906a7f89e332e154a
+  metadata.gz: b28ca284de2cdcaca6cbfda133b47d7582ebc7b0781ab49ea8cd589a2c1ebb93638341ac5d633f853118fdd385722f1baf5328893a24ddef033c764229d9f663
+  data.tar.gz: a89d029c7572c597f8da49d1a2bde41bdb50ad6413559113fdb5ddaf1ea488a2fdac03b979154b923d4262144491c9a826e8f4791c4bc9bcfc3afebed6f41cb1

data/README.md

@@ -1,32 +1,43 @@
 # xero-ruby
-Xero Ruby SDK for OAuth 2.0 generated from [Xero API OpenAPI Spec](https://github.com/XeroAPI/Xero-OpenAPI)
+Xero Ruby SDK for OAuth 2.0 generated from [Xero API OpenAPI Spec](https://github.com/XeroAPI/Xero-OpenAPI).
 
 [![RubyGem](https://img.shields.io/badge/xero--ruby%20gem-v0.2.4-brightgreen)](https://rubygems.org/gems/xero-ruby)
 
-## Current release of SDK with OAuth 2.0 support
-Xero Ruby SDK supports Xero's OAuth2.0 authentication (token generation & refresh) and supports the following Xero API sets.
-* [accounting](https://developer.xero.com/documentation/api/api-overview)
-* [assets](https://developer.xero.com/documentation/assets-api/overview)
-* [projects](https://developer.xero.com/documentation/projects/overview-projects)
+# Documentation
+Xero Ruby SDK supports Xero's OAuth2.0 authentication and supports the following Xero API sets.
 
-Coming soon
-* bank feeds
-* payroll (AU))
+## APIS
+* [Accounting Api Docs](/docs/accounting/AccountingApi.md)
+* [Asset Api Docs](/docs/assets/AssetApi.md)
+* [Project Api Docs](docs/projects/ProjectApi.md)
+
+## Models
+* [Accounting Models Docs](/docs/accounting/)
+* [Asset Models Docs](/docs/assets/)
+* [Project Models Docs](/docs/projects/)
+
+### Coming soon
+* payroll (AU)
 * payroll (NZ/UK)
 * files
 * xero hq
+* bank feeds
+
+## Sample Apps
+We have two apps showing SDK usage.
+* https://github.com/XeroAPI/xero-ruby-oauth2-starter (**Sinatra** - session based / getting started)
+* https://github.com/XeroAPI/xero-ruby-oauth2-app (**Rails** - token management / full examples)
 
 ## Looking for OAuth 1.0a support?
-Check out the [Xeroizer](https://github.com/waynerobinson/xeroizer) gem (maintained by community)
+Check out the [Xeroizer](https://github.com/waynerobinson/xeroizer) gem (maintained by community).
 
 ---
 ## Installation
-This SDK is published as a gem on RubyGems as [xero-ruby](https://rubygems.org/gems/xero-ruby) To install this gem to your current gemset, run:
-
+To install this gem to your current gemset.
 ```
 gem install 'xero-ruby'
 ```
-Or, add this to your gemfile:
+Or add to your gemfile and run `bundle install`.
 ```
 gem 'xero-ruby'
 ```
@@ -36,16 +47,12 @@ gem 'xero-ruby'
 * Login to your Xero developer [/myapps](https://developer.xero.com/myapps) dashboard & create an API application and note your API app's credentials.
 
 ### Creating a Client
-Require the gem:
+* Get the credential values from an API application at https://developer.xero.com/myapps/.
+* Include [neccesary scopes](https://developer.xero.com/documentation/oauth2/scopes) as comma seperated list
+    * example => "`openid profile email accounting.transactions accounting.settings`"
 ```
 require 'xero-ruby'
 ```
-Then create a client by passing in a named hash object `credentials:`.
-
-> *client_id*, *client_secret*, *redirect_uri*: Get this from your API application in /myapps dashboard.
-  *scopes*: Include scopes as comma seperated list, https://developer.xero.com/documentation/oauth2/scopes
-  **ex:** 'openid profile email accounting.transactions'
-
 ```ruby
 creds = {
   client_id: ENV['CLIENT_ID'],
@@ -56,48 +63,63 @@ creds = {
 xero_client ||= XeroRuby::ApiClient.new(credentials: creds)
 ```
 
-## Authorization & Callback
-All API requests require a valid access token to be set on the client. If this is the first time you are calling the Xero API on a users behalf you will need to generate an authorized token set, which will look something like this:
-```json
-{
-  "id_token": "xxx.yyy.zz",
-  "access_token": "xxx.yyy.zzz",
-  "expires_in": 1800,
-  "token_type": "Bearer",
-  "refresh_token": "xxxxxx",
-  "scope": "email profile openid accounting.transactions offline_access"
-}
-```
+## User Authorization & Callback
+All API requests require a valid access token to be set on the client.
 
-To generate a valid token_set with this SDK from Xero, have your user follow the authorization url:
+To generate a valid `token_set` send a user to the `authorization_url`:
 ```ruby
 @authorization_url = xero_client.authorization_url
-# https://login.xero.com/identity/connect/authorize?response_type=code&client_id=<xxx>&redirect_uri=<redirect_uri>&scope=<scopes>
+
+redirect_to @authorization_url
 ```
 
-> The `get_token_set_from_callback` method will set the `token_set` on the client, however you can also initialize a client and set the `token_set` explicitely using `set_token_set` or `refresh_token_set`.
+Xero will then redirect back to the URI defined in your ENV['REDIRECT_URI'] variable.
+*This must match **exactly** with the variable in your /myapps dashboard.*
 
+In your callback route catch, calling `get_token_set_from_callback` will exchange the temp code in your params, with a valid `token_set` that you can use to make API calls.
 ```ruby
-# /my-redirect-uri
+# => http://localhost:3000/oauth/callback
+
 token_set = xero_client.get_token_set_from_callback(params)
 
-# this is where you will want to save the token set for future API usage..
-# ex: user.update!(xero_token_set: token_set)
+# save token_set JSON in a datastore in relation to the user authentication
+```
 
-# if you already saved a token_set you don't need the user to authenticate via UI
-# and can just set the token on the client by refreshing it.
+## Making API calls once you have a token_set
+For use outside of the initial auth flow, setup the client by passing the whole token_set to `refresh_token_set` or `set_token_set`.
+```ruby
 xero_client.refresh_token_set(user.token_set)
+
+xero_client.set_token_set(user.token_set)
 ```
+A `token_set` contains data about your API connection most importantly :
+* `access_token`
+* `refresh_token`
+* `expiry`
 
-## Token & SDK Helpers
+**An `access_token` is valid 30 minutes and a `refresh_token` is valid for 60 days**
 
-Token Sets contain information about your API connection, but most important are the access_token, refresh_token, and the expiry:
-* An `access_token` is valid 30 minutes and a `refresh_token` is valid for 60 days
+Example Token set:
+> You can decode the `id_token` & `access_token` for additional metadata by using a [decoding library](https://github.com/jwt/ruby-jwt):
+```json
+{
+  "id_token": "xxx.yyy.zz",
+  "access_token": "xxx.yyy.zzz",
+  "expires_in": 1800,
+  "token_type": "Bearer",
+  "refresh_token": "xxxxxx",
+  "scope": "email profile openid accounting.transactions offline_access"
+}
+```
 
+## Token & SDK Helpers
+Refresh/connection helpers
 ```ruby
 @token_set = xero_client.refresh_token_set(user.token_set)
 
-# TIP: the `updatedDateUtc` will show you the most recently authorized Tenant (AKA Organisation)
+# Xero's tokens can potentially facilitate (n) org connections in a single token. It is important to store the `tenantId` of the Organisation your user wants to read/write data.
+
+# The `updatedDateUtc` will show you the most recently authorized Tenant (AKA Organisation)
 connections = xero_client.connections
 [{
   "id" => "xxx-yyy-zzz",
@@ -108,97 +130,157 @@ connections = xero_client.connections
   "updatedDateUtc" => "2020-04-15T22:37:10.4943410"
 }]
 
-# disconnect an org from a user's connections. Pass the connection ['id'] not ['tenantId'].
+# disconnect an org from a user's connections. Pass the connection ['id'] not ['tenantId']. Useful if you want to enforce only a single org connection per token.
 remaining_connections = xero_client.disconnect(connections[0]['id'])
 
-# set token_set
+# set a refreshed token_set
 token_set = xero_client.set_token_set(user.token_set)
 
-# access token_set
+# access token_set once it is set on the client
 token_set = xero_client.token_set
 ```
 
-## API Usage
->  Comprehensive xero-ruby API usage is showcased here: https://github.com/XeroAPI/xero-ruby-oauth2-app
+Example token expiry helper
+```ruby
+require 'jwt'
+
+def token_expired?
+  token_expiry = Time.at(decoded_access_token['exp'])
+  token_expiry > Time.now
+end
 
-Here is the basic workflow of using SDK once you have a valid `access_token` (and `token_set`) stored on an instance of the `xero_client`
+def decoded_access_token
+  JWT.decode(token_set['access_token'], nil, false)[0]
+end
+```
 
+## API Usage
 ```ruby
   require 'xero-ruby'
 
-  # reference `Authorization & Callback` to first store a valid token_set on the `xero_client`
   xero_client.refresh_token_set(user.token_set)
 
-  # Using the Accounting API set (https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/accounting_api.rb)
-
-  # Examples
-  invoices = xero_client.accounting_api.get_invoices(user.active_tenant_id).invoices
-  accounts = xero_client.accounting_api.get_accounts(user.active_tenant_id).accounts
-  contacts = xero_client.accounting_api.get_contacts(user.active_tenant_id).contacts
-
-  contacts = xero_client.accounting_api.get_contacts(current_user.active_tenant_id).contacts
-  invoices = { invoices: [{ type: XeroRuby::Accounting::Invoice::ACCREC, contact: { contact_id: contacts[0].contact_id }, line_items: [{ description: "Acme Tires", quantity: BigDecimal("2.0"), unit_amount: BigDecimal("20.99"), account_code: "600", tax_type: XeroRuby::Accounting::TaxType::NONE }], date: "2019-03-11", due_date: "2018-12-10", reference: "Website Design", status: XeroRuby::Accounting::Invoice::DRAFT }]}
-  invoice = xero_client.accounting_api.create_invoices(current_user.active_tenant_id, invoices).invoices.first
+  tenant_id = user.active_tenant_id
+  # example of how to store the `tenantId` of the specific tenant (aka organisation)
 
-  # all money and fields requiring advanced precision utilize BigDecimal
-  puts invoice.unit_amount
-  => 0.2099e2
+  # https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/accounting_api.rb
   
-  puts invoice.unit_amount.class 
-  => BigDecimal
+  # Get Accounts
+  accounts = xero_client.accounting_api.get_accounts(tenant_id).accounts
 
-  puts invoice.unit_amount.to_s("F")
-  => "20.99"
-
-  # or if using Rails https://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_to_currency
-  number_to_currency(invoice.unit_amount, :unit => "$")
+  # Create Invoice
+  invoices = { invoices: [{ type: XeroRuby::Accounting::Invoice::ACCREC, contact: { contact_id: contacts[0].contact_id }, line_items: [{ description: "Big Agency", quantity: BigDecimal("2.0"), unit_amount: BigDecimal("50.99"), account_code: "600", tax_type: XeroRuby::Accounting::TaxType::NONE }], date: "2019-03-11", due_date: "2018-12-10", reference: "Website Design", status: XeroRuby::Accounting::Invoice::DRAFT }]}
+  invoice = xero_client.accounting_api.create_invoices(tenant_id, invoices).invoices.first
 
-  # creating an object History record
-  payment = xero_client.accounting_api.get_payments(current_user.active_tenant_id).payments.first
-  history_records = { history_records:[ { details: "This payment now has some History #{rand(10000)}" } ]}
-  payment_history = xero_client.accounting_api.create_payment_history(user.active_tenant_id, payment.payment_id, history_records)
+  # Create History
+  payment = xero_client.accounting_api.get_payments(tenant_id).payments.first
+  history_records = { history_records: [{ details: "This payment now has some History!" }]}
+  payment_history = xero_client.accounting_api.create_payment_history(tenant_id, payment.payment_id, history_records)
 
-  # creating an object Attachment record
-  account = xero_client.accounting_api.get_accounts(current_user.active_tenant_id).accounts.first
+  # Create Attachment
+  account = xero_client.accounting_api.get_accounts(tenant_id).accounts.first
   file_name = "an-account-filename.png"
   opts = {
-    include_online: true # Boolean | Allows an attachment to be seen by the end customer within their online invoice
+    include_online: true
   }
   file = File.read(Rails.root.join('app/assets/images/xero-api.png'))
-  attachment = xero_client.accounting_api.create_account_attachment_by_file_name(current_user.active_tenant_id, @account.account_id, file_name, file, opts)
+  attachment = xero_client.accounting_api.create_account_attachment_by_file_name(tenant_id, @account.account_id, file_name, file, opts)
 
-  # Using the Asset API set (https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/asset_api.rb)
+  # https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/asset_api.rb
+  
+  # Create Asset
   asset = {
     "assetName": "AssetName: #{rand(10000)}",
     "assetNumber": "Asset: #{rand(10000)}",
     "assetStatus": "DRAFT"
   }
-  asset = xero_client.asset_api.create_asset(current_user.active_tenant_id, asset)
+  asset = xero_client.asset_api.create_asset(tenant_id, asset)
+
+  # https://github.com/XeroAPI/xero-ruby/blob/master/docs/projects/ProjectApi.md
 
-  # Using the Project API set (https://github.com/XeroAPI/xero-ruby/blob/master/docs/projects/ProjectApi.md)
-  projects = xero_client.project_api.get_projects(current_user.active_tenant_id).items
+  # Get Projects
+  projects = xero_client.project_api.get_projects(tenant_id).items
 ```
 
-If you have use cases outside of these examples or this readmy, please let us know!
+## BigDecimal
+All monetary and fields and a couple quantity fields utilize BigDecimal
+```ruby
+  puts invoice.unit_amount
+  => 0.2099e2
+  
+  puts invoice.unit_amount.class 
+  => BigDecimal
+
+  puts invoice.unit_amount.to_s("F")
+  => "20.99"
 
-## Sample App
-The best resource to understanding how to best leverage this SDK is to clone down our Sample Rails application which showcases all the features of this project. The sample app can help you quickly understand how to:
-> https://github.com/XeroAPI/xero-ruby-oauth2-app
+  # Rails method-number_to_currency
+  number_to_currency(invoice.unit_amount, :unit => "$")
+```
 
-* Complete the OAuth2.0 Authorization flow
-* Store token_sets against a user object in a DB
-* Storing info about active connections
-* Change the active tenant & make api calls to multiple orgs
-* Refreshing your token sets
-* Decoding your token_set items and strategy around how/when to refresh
-* Disconnecting a connection for a user
+## Querying & Filtering
+Examples for the `opts` (_options_) parameters most endpoints support. This is an area of focus and improvement. If you have a complex filering/sorting/where usage that is not supported please [open an issue](https://github.com/XeroAPI/xero-ruby/issues).
+```ruby
+# Invoices
+ opts = {
+  page: 1,
+  where: {
+    type: ['=', XeroRuby::Accounting::Invoice::ACCREC],
+    fully_paid_on_date: (DateTime.now - 6.month)..DateTime.now,
+    amount_due: ['>=', 0],
+    reference: ['=', "Website Design"],
+    invoice_number: ['=', "INV-0001"],
+    contact_id: ['=', 'contact-uuid-xxxx-xxx-xxxxxxx'],
+    contact_number: ['=', "the-contact-number"],
+    # date: (DateTime.now - 2.year)..DateTime.now
+    # ▲ you can pass a range ▼ or a date & operator
+    date: ['>=', DateTime.now - 2.year],
+    status: ['=', XeroRuby::Accounting::Invoice::PAID]
+  }
+}
+xero_client.accounting_api.get_invoices(tenant_id, opts).invoices
+
+# Contacts 
+opts = {
+  if_modified_since: (DateTime.now - 1.weeks).to_s,
+  # ▼ ordering by strings needs PascalCase convention
+  order: 'UpdatedDateUtc DESC',
+  where: {
+    is_customer: ['==', true],
+    is_supplier: ['==', true]
+  }
+}
+xero_client.accounting_api.get_contacts(tenant_id, opts).contacts
+
+# Bank Transactions
+opts = {
+  if_modified_since: (DateTime.now - 1.year).to_s,
+  where: { type: ['==', XeroRuby::Accounting::BankTransaction::SPEND] },
+  order: 'UpdatedDateUtc DESC',
+  page: 2,
+  unitdp: 4 # (Unit Decimal Places)
+}
+xero_client.accounting_api.get_bank_transactions(tenant_id, opts).bank_transactions
+
+# Bank Transfers
+opts = {
+  if_modified_since: (DateTime.now - 1.month).to_s,
+  where: {
+    amount: [">=" , 999.99]
+  },
+  order: 'Amount ASC'
+}
+xero_client.accounting_api.get_bank_transfers(tenant_id, opts).bank_transfers
+```
+### NOTE
+1) Not all `opts` parameter combinations are available for all endpoints, and there are likely some undiscovered edge cases. If you encounter a filter / sort / where clause that seems buggy open an issue and we will dig.
 
-## Additional Documentation for API Endpoints
+2) Some opts string values may need PascalCasing to match casing defined in our [core API docs](https://developer.xero.com/documentation/api/api-overview).
+    * `opts = { order: 'UpdatedDateUtc DESC'}`
 
-### APIS
-* [Accounting Api Docs](/docs/accounting/AccountingApi.md)
-* [Asset Api Docs](/docs/assets/AssetApi.md)
+3) If you have use cases outside of these examples let us know.
 
-## Models
-* [Accounting Models Docs](/docs/accounting/)
-* [Asset Models Docs](/docs/assets/)
+## Sample App
+The best resource to understanding how to best leverage this SDK is the sample applications showing all the features of the gem.
+> https://github.com/XeroAPI/xero-ruby-oauth2-starter (Sinatra - simple getting started)
+> https://github.com/XeroAPI/xero-ruby-oauth2-app (Rails - full featured examples)

data/build_notes.md

@@ -1,4 +1,4 @@
-Developing gem locally
+# Developing gem locally
 
 > xero-ruby
 ```bash
@@ -7,16 +7,46 @@ mv xero-ruby-<vsn>.gem xero-ruby.gem
 ```
 
 > xero-ruby-oauth2-app
-
 Replace gem file with local path:
 ```bash
 gem 'xero-ruby', path: '/Users/chris.knight/code/sdks/xero-ruby/'
 bundle install
 ```
 
-Deploying to Rubygems
+# Deploying to Rubygems
 
 ```bash
 gem build
-gem push xero-ruby-<vsn>.gem 
-```
+gem push xero-ruby-<vsn>.gem
+```
+
+# manual updates
+account.rb 
+```ruby
+# duplicate definitions generated: https://github.com/XeroAPI/xero-ruby/issues/53#issuecomment-668893305
+# EMPTY = "".freeze
+```
+
+organisation.rb
+```ruby
+# duplicate definitions generated: https://github.com/XeroAPI/xero-ruby/issues/53#issuecomment-668893305
+# NONE = "NONE".freeze
+
+# duplicate definitions generated: https://github.com/XeroAPI/xero-ruby/issues/53#issuecomment-668893305
+# ACCOUNTING_PRACTICE = "ACCOUNTING_PRACTICE".freeze
+# COMPANY = "COMPANY".freeze
+# CHARITY = "CHARITY".freeze
+# CLUB_OR_SOCIETY = "CLUB_OR_SOCIETY".freeze
+# LOOK_THROUGH_COMPANY = "LOOK_THROUGH_COMPANY".freeze
+# NOT_FOR_PROFIT = "NOT_FOR_PROFIT".freeze
+# PARTNERSHIP = "PARTNERSHIP".freeze
+# S_CORPORATION = "S_CORPORATION".freeze
+# SELF_MANAGED_SUPERANNUATION_FUND = "SELF_MANAGED_SUPERANNUATION_FUND".freeze
+# SOLE_TRADER = "SOLE_TRADER".freeze
+# SUPERANNUATION_FUND = "SUPERANNUATION_FUND".freeze
+# TRUST = "TRUST".freeze
+```
+
+# Debugging in mustache templates + open api generator
+{{{this}}}
+{{{.}}}

data/docs/accounting/Account.md

@@ -47,7 +47,7 @@ instance = XeroRuby::Accounting::Account.new(code: 4400,
                                  reporting_code: null,
                                  reporting_code_name: null,
                                  has_attachments: false,
-                                 updated_date_utc: null,
+                                 updated_date_utc: /Date(1573755038314)/,
                                  add_to_watchlist: null,
                                  validation_errors: null)
 ```