xero-ruby 2.4.1 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9971f81d76c9c1b3d6533ecb022cf10a28e43ef1e13ff80e3e4358e70d6b528c
-  data.tar.gz: ea190c78416aa8fd3a4bfdbec2be51e01c4be862b6fc9fb591d4103c24754bf0
+  metadata.gz: fcc8e88d077eb5b42f9a9c8a206ce6c7fb62589e7179932764a70cc28c3f821a
+  data.tar.gz: 8c25945749aaca49892462186f749701255022d05ea498645a3b1e59c10a5e52
 SHA512:
-  metadata.gz: 6119180c2690484854f32fdef63d9b7e76ad7e78c5b5487174fc41cf7df827427d77dc901c9f10edf9a710898833a11c2aa7542c5ac3cc0abdf5319606f8c559
-  data.tar.gz: 73585f179d4d148dfc47bef5dadf1ea7586c4872ab827aa11a0116e3379ae4a2f83aa01fd941a78eefddd37895711af52c06037344d424e91135b78b2bd3b6b6
+  metadata.gz: 4196ec14ceaa6179bbbedb856b447e7af947ba96e4af24ab8130835af5660a8e6787fbf3261c3f6c5c605d0f81436559bd37e1e0a7252bab42feb752f4634d31
+  data.tar.gz: c99e89b1f45563b72023ad5d5ceb3632fe5661068ad5ee89d672194fca72ddccbb1967d9f9796098d12ff9b649f03dfa5b26d3eb08b3daf756bef0e3a7f3fe5f

data/README.md

@@ -1,176 +1,228 @@
 # xero-ruby
-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)
-
-# Documentation
-Xero Ruby SDK supports Xero's OAuth2.0 authentication and supports the following Xero API sets.
-
-## API Client Docs
-* [Accounting Api Docs](/docs/accounting/AccountingApi.md)
-* [Asset Api Docs](/docs/assets/AssetApi.md)
-* [Project Api Docs](docs/projects/ProjectApi.md)
-* [File Api Docs](docs/files/FileApi.md)
-* [Payroll Docs (AU)](docs/payroll_au/PayrollAuApi.md)
-* [Payroll Docs (NZ)](docs/payroll_nz/PayrollNzApi.md)
-* [Payroll Docs (UK)](docs/payroll_uk/PayrollUkApi.md)
-
-## API Model Docs
-* [Accounting Models Docs](/docs/accounting/)
-* [Asset Models Docs](/docs/assets/)
-* [Project Models Docs](/docs/projects/)
-* [File Models Docs](/docs/files/)
-* [Payroll Models (AU)](docs/payroll_au/)
-* [Payroll Models (NZ)](docs/payroll_nz/)
-* [Payroll Models (UK)](docs/payroll_uk/)
-
-## 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)
-
-![sample-app](https://i.imgur.com/OOEn55G.png)
-
-## Looking for OAuth 1.0a support?
-Check out the [Xeroizer](https://github.com/waynerobinson/xeroizer) gem (maintained by community).
-
----
-## Installation
-To install this gem to your current gemset.
+[![Gem Version](https://badge.fury.io/rb/xero-ruby.svg)](https://badge.fury.io/rb/xero-ruby)
+[![Github forks](https://img.shields.io/github/forks/XeroAPI/xero-ruby.svg)](https://github.com/XeroAPI/xero-ruby/network)
+[![Github stars](https://img.shields.io/github/stars/XeroAPI/xero-ruby.svg)](https://github.com/XeroAPI/xero-ruby/stargazers)
+![total downloads](https://ruby-gem-downloads-badge.herokuapp.com/xero-ruby?type=total)
+
+The xero-ruby SDK makes it easy for developers to access Xero's APIs in their Ruby code, and build robust applications and software using small business & general ledget accounting data.
+# Table of Contents
+- [API Client documentation](#api-client-documentation)
+- [Sample Applications](#sample-applications)
+- [Xero Account Requirements](#xero-account-requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Authentication](#authentication)
+- [Custom Connections](#custom-connections)
+- [API Clients](#api-clients)
+- [Helper Methods](#helper-methods)
+- [Usage Examples](#usage-examples)
+- [SDK conventions](#sdk-conventions)
+- [Contributing](#contributing)
+
+<hr>
+
+## API Client documentation
+This SDK supports full method coverage for the following Xero API sets:
+
+| API Set | Description |
+| --- | --- |
+| [`Accounting`](https://xeroapi.github.io/xero-ruby/accounting/index.html) | The Accounting API exposes accounting functions of the main Xero application *(most commonly used)*
+| [Assets](https://xeroapi.github.io/xero-ruby/assets/index.html) | The Assets API exposes fixed asset related functions of the Xero Accounting application |
+| [Files](https://xeroapi.github.io/xero-ruby/files/index.html) | The Files API provides access to the files, folders, and the association of files within a Xero organisation |
+| [Projects](https://xeroapi.github.io/xero-ruby/projects/index.html) | Xero Projects allows businesses to track time and costs on projects/jobs and report on profitability |
+| [Payroll (AU)](https://xeroapi.github.io/xero-ruby/payroll_au/index.html) | The (AU) Payroll API exposes payroll related functions of the payroll Xero application |
+| [Payroll (UK)](https://xeroapi.github.io/xero-ruby/payroll_uk/index.html) | The (UK) Payroll API exposes payroll related functions of the payroll Xero application |
+| [Payroll (NZ)](https://xeroapi.github.io/xero-ruby/payroll_nz/index.html) | The (NZ) Payroll API exposes payroll related functions of the payroll Xero application |
+| [`Ruby Models`](/docs/) | Directory of markdown files, describing the object models for all supported API sets |
+
+<img src="https://i.imgur.com/0MsvkGB.png" alt="drawing" width="350"/>
+
+<hr>
+
+## Sample Applications
+Sample apps can get you started quickly with simple auth flows to advanced usage.
+| Sample App | Description | Screenshot |
+| --- | --- | --- |
+| [`xero-ruby-oauth2-starter`](https://github.com/XeroAPI/Xero-ruby-oauth2-starter) | A Sinatra application showing the basic getting started code to work with the sdk | <img src="https://i.imgur.com/9H4F98M.png" alt="drawing" width="300"/>
+| [`xero-ruby-oauth2-app`](https://github.com/XeroAPI/Xero-ruby-oauth2-app) | Complete rails app with +95% of api set examples, complex filters, pagination, and user/token management in postgres | <img src="https://i.imgur.com/XsAp9Ww.png" alt="drawing" width="500"/>
+| [`xero-ruby-custom-connections-starter`](https://github.com/XeroAPI/xero-ruby-custom-connections-starter) | A getting started Sinatra app showing Custom Connections - a Xero [premium option](https://developer.xero.com/documentation/oauth2/custom-connections) for building M2M integrations to a single org | <img src="https://i.imgur.com/YEkScui.png" alt="drawing" width="300"/>
+
+<hr>
+
+## Xero Account Requirements
+- Create a [free Xero user account](https://www.xero.com/us/signup/api/)
+- Login to your Xero developer [dashboard](https://developer.xero.com/app/manage) and create an API application
+- Copy the credentials from your API app and store them using a secure ENV variable strategy
+- Decide the [neccesary scopes](https://developer.xero.com/documentation/oauth2/scopes) for your app's functionality
+
+# Installation
+To install this gem to your project
 ```
 gem install 'xero-ruby'
 ```
-Or add to your gemfile and run `bundle install`.
+Or add to your gemfile and run `bundle install`
 ```
 gem 'xero-ruby'
 ```
 
-## Getting Started
-* Create a [free Xero user account](https://www.xero.com/us/signup/api/)
-* 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
-* 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'
-```
+---
+## Configuration
 ```ruby
+require 'xero-ruby'
+
 creds = {
   client_id: ENV['CLIENT_ID'],
   client_secret: ENV['CLIENT_SECRET'],
   redirect_uri: ENV['REDIRECT_URI'],
-  scopes: ENV['SCOPES']
+  scopes: ENV['SCOPES'],
+  state: "Optional value to pass through auth flow"
 }
 xero_client ||= XeroRuby::ApiClient.new(credentials: creds)
 ```
 
-## User Authorization & Callback
-All API requests require a valid access token to be set on the client.
+For additional [config](/lib/xero-ruby/configuration.rb) options you can pass an optional named parameter `config: {}`
+```ruby
+config = { timeout: 30, debugging: true }
+@xero_client ||= XeroRuby::ApiClient.new(credentials: creds, config: config)
+```
+---
+## Authentication
+All API requests go through Xero's OAuth2.0 gateway and require a valid `access_token` to be set on the `xero_client`, which autmoatically appends the `access_token` [JWT](https://jwt.io/) to the header of each request.
+
+If you are making an API call for the first time:
 
-To generate a valid `token_set` send a user to the `authorization_url`:
+1. Send the user to the Xero authorization URL
 ```ruby
 @authorization_url = xero_client.authorization_url
-
 redirect_to @authorization_url
 ```
-
-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.
+2. The user will authorize your API application and be sent to your `redirect_uri`
 ```ruby
-# => http://localhost:3000/oauth/callback
-
-token_set = xero_client.get_token_set_from_callback(params)
-
-# save token_set JSON in a datastore in relation to the user authentication
+ENV['REDIRECT_URI']
+=> /xero-callback?code=xyz123
 ```
-
-## 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`.
+3. You exchange a temporary `authorization_code` for a valid `token_set`
 ```ruby
-xero_client.refresh_token_set(user.token_set)
-
-xero_client.set_token_set(user.token_set)
+@token_set = @xero_client.get_token_set_from_callback(params)
+# save the @token_set
 ```
-A `token_set` contains data about your API connection most importantly :
-* `access_token`
-* `refresh_token`
-* `expiry`
 
-**An `access_token` is valid 30 minutes and a `refresh_token` is valid for 60 days**
+It is reccomended that you store this token set JSON in a datastore in relation to the user who has authenticated the Xero API connection. Each time you want to call the Xero API, you will need to access the previously generated token set, initialize it on the SDK `xero_client`, and refresh the `access_token` prior to making API calls.
+
+### Token Set
+| key | value | description |
+| --- | --- | --- |
+| id_token: | "xxx.yyy.zzz" | [OpenID Connect](https://openid.net/connect/) token returned if `openid profile email` scopes accepted |
+| access_token: | "xxx.yyy.zzz" | [Bearer token](https://oauth.net/2/jwt/) with a 30 minute expiration required for all API calls |
+| expires_in: | 1800 | Time in seconds till the token expires - 1800s is 30m |
+| refresh_token: | "XXXXXXX" | Alphanumeric string used to obtain a new Token Set w/ a fresh access_token - 60 day expiry |
+| scope: | "email profile openid accounting.transactions offline_access" | The Xero permissions that are embedded in the `access_token` |
 
-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
+Example Token Set JSON:
+```
 {
   "id_token": "xxx.yyy.zz",
   "access_token": "xxx.yyy.zzz",
   "expires_in": 1800,
   "token_type": "Bearer",
-  "refresh_token": "xxxxxx",
+  "refresh_token": "xxxxxxxxx",
   "scope": "email profile openid accounting.transactions offline_access"
 }
 ```
+---
+## Custom Connections 
+
+Custom Connections are a Xero [premium option](https://developer.xero.com/documentation/oauth2/custom-connections) used for building M2M integrations to a single organisation. A custom connection uses OAuth2.0's [`client_credentials`](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) grant which eliminates the step of exchanging the temporary code for a token set.
 
-## Token & SDK Helpers
-Refresh/connection helpers
+To use this SDK with a Custom Connections:
 ```ruby
-@token_set = xero_client.refresh_token_set(user.token_set)
-
-# 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",
-  "tenantId" => "xxx-yyy-zzz",
-  "tenantType" => "ORGANISATION",
-  "tenantName" => "Demo Company (US)",
-  "createdDateUtc" => "2019-11-01T20:08:03.0766400",
-  "updatedDateUtc" => "2020-04-15T22:37:10.4943410"
-}]
-
-# 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 a refreshed token_set
-token_set = xero_client.set_token_set(user.token_set)
-
-# access token_set once it is set on the client
-token_set = xero_client.token_set
+CREDENTIALS = {
+  client_id: ENV['CLIENT_ID'],
+  client_secret: ENV['CLIENT_SECRET'],
+  grant_type: 'client_credentials'
+}
+
+xero_client = XeroRuby::ApiClient.new(credentials: CREDENTIALS)
+
+@token_set = xero_client.get_client_credentials_token
+# save @token_set
+
+@invoices = xero_client.accounting_api.get_invoices('').invoices
 ```
 
-Example token expiry helper
+Because Custom Connections are only valid for a single organisation you don't need to pass the `xero-tenant-id` as the first parameter to every method.
+
+However - due to the nature of how our SDK's are generated from our OpenAPI spec, the parameter remains which requires you to pass an empty string for now to use the SDK with a Custom Connection.
+
+---
+## API Clients
+You can access the different API sets and their available methods through the following:
+
 ```ruby
-require 'jwt'
+xero_client = XeroRuby::ApiClient.new(credentials: creds)
+
+xero_client.accounting_api
+xero_client.asset_api
+xero_client.project_api
+xero_client.files_api
+xero_client.payroll_au_api
+xero_client.payroll_nz_api
+xero_client.payroll_uk_api
+```
+---
+## Helper Methods
 
-def token_expired?
-  token_expiry = Time.at(decoded_access_token['exp'])
-  token_expiry < Time.now
-end
+Once you have a valid Token Set in your datastore, the next time you want to call the Xero API simply initialize a new `xero_client` and refresh the token set.
 
-def decoded_access_token
-  JWT.decode(token_set['access_token'], nil, false)[0]
+```ruby
+xero_client = XeroRuby::ApiClient.new(credentials: creds)
+ 
+if xero_client.token_expired?
+  @token_set = xero_client.refresh_token_set(user.token_set)
+else
+  @token_set = xero_client.set_token_set(user.token_set)
 end
-```
 
-## API Usage
+# example strategy
+user.token_set = @token_set if !@token_set["error"]
+user.xero_connections = xero_client.connections
+user.active_tenant_id = xero_client.last_connection
+user.save!
+
+xero_client.accounting_api.get_invoices(xero_client.last_connection['tenantId']).invoices
+```
 
+This will set the access_token on the client and return the refreshed `token_set` that you need to save in your datastore to keep the connection alive until you or the user disconnect.
+
+A full list of the SDK client's methods:
+
+| method | description |
+| --- | --- |
+| xero_client.`authorization_url` | returns the authorize URL string to send a new user to for API authorization |
+| xero_client.`get_token_set_from_callback`(params) | returns and generates a `token_set` from a temporary code for an `authorization_code` configured client only. Params are the url params. |
+| xero_client.`get_client_credentials_token` | returns and generates a `token_set` for a `client_credentials` configured client only  |
+| xero_client.`refresh_token_set`(token_set) | returns a refreshed token_set |
+| xero_client.`revoke_token`(token_set) | removes all a user's org connections and revokes the refresh_token |
+| xero_client.`disconnect`(connection_id) | disconnects an org connection from a user's token permissions |
+| xero_client.`connections` | returns an array of the user's currently connected Xero orgs |
+| xero_client.`last_connection` | returns the `xero-tenant-id` of the most recently connected Xero org |
+| xero_client.`set_token_set`(token_set) | returns a boolean and sets a token on the client - `token_set` containing an access_token & refresh_token |
+| xero_client.`set_access_token`(access_token) | How you can set an `access_token` by itself |
+| xero_client.`set_id_token`(id_token) | How you can set an `id_token` by itself |
+| xero_client.`token_expired?` | returns a boolean if token_set['access_token'] is expired |
+| xero_client.`token_set` | returns the token set if one is set on the client |
+| xero_client.`access_token` | returns the `access_token` if one is set on the client |
+| xero_client.`id_token` | returns the `id_token` if one is set on the client |
+| xero_client.`decoded_access_token` | Decoded JWT exposing OAuth2.`0` meta details about the token |
+| xero_client.`decoded_id_token` | Decoded JWT containing the user meta details that can be used to implement SSO or SSU to Lead |
+---
+## Usage Examples
 ### Accounting API
 ```ruby
 require 'xero-ruby'
 
-xero_client.refresh_token_set(user.token_set)
-
-tenant_id = user.active_tenant_id
-# example of how to store the `tenantId` of the specific tenant (aka organisation)
-
-# https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/accounting_api.rb
+xero_client.refresh_token_set(user_token_set)
+tenant_id = xero_client.last_connection
 
 # Get Accounts
 accounts = xero_client.accounting_api.get_accounts(tenant_id).accounts
@@ -179,6 +231,13 @@ accounts = xero_client.accounting_api.get_accounts(tenant_id).accounts
 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
 
+# return data as a snake_case hash
+puts invoices.to_attributes
+=> {type: 'ACCREC', line_items: [...]}
+
+puts invoices.to_hash(downcase: false)
+=> {'Type': 'ACCREC', 'LineItems': [...]}
+
 # Create History
 payment = xero_client.accounting_api.get_payments(tenant_id).payments.first
 history_records = { history_records: [{ details: "This payment now has some History!" }]}
@@ -194,59 +253,9 @@ file = File.read(Rails.root.join('app/assets/images/xero-api.png'))
 attachment = xero_client.accounting_api.create_account_attachment_by_file_name(tenant_id, @account.account_id, file_name, file, opts)
 ```
 
-### Assets API
-```ruby
-# 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(tenant_id, asset)
-```
-
-### Project API
-```ruby
-# https://github.com/XeroAPI/xero-ruby/blob/master/docs/projects/ProjectApi.md
-
-# Get Projects
-projects = xero_client.project_api.get_projects(tenant_id).items
-```
-
-### Files API
-```ruby
-# https://github.com/XeroAPI/xero-ruby/blob/master/docs/files/FileApi.md
-
-# Get Files
-opts = {
-  pagesize: 50, # Integer | pass an optional page size value
-  page: 2, # Integer | number of records to skip for pagination
-  sort: 'CreatedDateUTC DESC' # String | values to sort by
-}
-  
-files = xero_client.files_api.get_files(tenant_id, opts).files
-```
-
-### Payroll API(s)
-```ruby
-# https://github.com/XeroAPI/xero-ruby/blob/master/docs/payroll_au/PayrollAuApi.md
-employee_id = 'employee_uuid'
-employee = xero_client.payroll_au_api.get_employee(tenant_id, employee_id).employee
-
-
-# https://github.com/XeroAPI/xero-ruby/blob/master/docs/payroll_nz/PayrollNzApi.md
-timesheet_id = 'timesheeet_uuid'
-timesheet = xero_client.payroll_nz_api.approve_timesheet(tenant_id, timesheet_id).timesheets
-
-
-# https://github.com/XeroAPI/xero-ruby/blob/master/docs/payroll_uk/PayrollUkApi.md
-employee_id = 'employee_uuid'
-wages = xero_client.payroll_uk_api.get_employee_salary_and_wages(tenant_id, employee_id, opts).salary_and_wages
-```
-
-## BigDecimal
+---
+## SDK conventions
+### BigDecimal
 All monetary and fields and a couple quantity fields utilize BigDecimal
 ```ruby
   puts invoice.unit_amount
@@ -262,8 +271,8 @@ All monetary and fields and a couple quantity fields utilize BigDecimal
   number_to_currency(invoice.unit_amount, :unit => "$")
 ```
 
-## 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).
+### Querying & Filtering
+Examples for `opts` (aka _options_) parameters that most endpoints support. 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 = {
@@ -276,7 +285,7 @@ Examples for the `opts` (_options_) parameters most endpoints support. This is a
     invoice_number: ['=', "INV-0001"],
     contact_id: ['=', 'contact-uuid-xxxx-xxx-xxxxxxx'],
     contact_number: ['=', "the-contact-number"],
-    # date: (DateTime.now - 2.year)..DateTime.now
+    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]
@@ -291,11 +300,20 @@ opts = {
   order: 'UpdatedDateUtc DESC',
   where: {
     is_customer: ['==', true],
-    is_supplier: ['==', true]
+    is_supplier: ['==', true],
+    name: ['StartsWith', 'Rick']
   }
 }
 xero_client.accounting_api.get_contacts(tenant_id, opts).contacts
 
+# for more complex chained filtering that requires a null check pass those in as a string
+# see https://developer.xero.com/documentation/api/requests-and-responses for more
+opts = {
+  where: {
+    email_address: '!=null&&EmailAddress.StartsWith("chris.knight@")'
+  }
+}
+
 # Bank Transactions
 opts = {
   if_modified_since: (DateTime.now - 1.year).to_s,
@@ -316,15 +334,48 @@ opts = {
 }
 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.
 
-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'}`
+- Not all `opts` parameter combinations are available for all endpoints
+
+- Some opts string values may need PascalCasing to match casing defined in our [core API docs](https://developer.xero.com/documentation/api/api-overview) like `opts = { order: 'UpdatedDateUtc DESC'}`
+
+---
+## Contributing
+PRs, issues, and discussion are highly appreciated and encouraged. Note that the majority of this project is generated code based on [Xero's OpenAPI specs](https://github.com/XeroAPI/Xero-OpenAPI) - PR's will be evaluated and pre-merge will be incorporated into the root generation templates.
+
+Please add tests for net new functionality and make existing test suite succeeds.
+
+`$ rspec spec/`
+### Versioning
+We do our best to keep OS industry `semver` standards, but we can make mistakes! If something is not accurately reflected in a version's release notes please let the team know.
+### Developing locally
+To develop or test this gem locally against your project we find the following development pattern easiest
+
+```bash
+cd xero-ruby
+gem build
+mv xero-ruby-<vsn>.gem xero-ruby.gem
+pwd
+=> /Users/your.user/code/sdks/xero-ruby/
+
+cd ..
+cd xero-ruby-oauth2-app/
+
+# xero-ruby-oauth2-app/Gemfile
+gem 'xero-ruby', path: '/Users/your.user/code/sdks/xero-ruby/'
+bundle install
+```
+
+## Participating in Xero’s developer community
+
+This SDK is one of a number of SDK’s that the Xero Developer team builds and maintains. We are grateful for all the contributions that the community makes. 
 
-3) If you have use cases outside of these examples let us know.
+Here are a few things you should be aware of as a contributor:
+* Xero has adopted the Contributor Covenant [Code of Conduct](https://github.com/XeroAPI/xero-ruby/blob/master/CODE_OF_CONDUCT.md), we expect all contributors in our community to adhere to it
+* If you raise an issue then please make sure to fill out the github issue template, doing so helps us help you 
+* You’re welcome to raise PRs. As our SDKs are generated we may use your code in the core SDK build instead of merging your code
+* We have a [contribution guide](https://github.com/XeroAPI/xero-ruby/blob/master/CONTRIBUTING.md) for you to follow when contributing to this SDK
+* Curious about how we generate our SDK’s? Have a [read of our process](https://devblog.xero.com/building-sdks-for-the-future-b79ff726dfd6) and have a look at our [OpenAPISpec](https://github.com/XeroAPI/Xero-OpenAPI)
+* This software is published under the [MIT License](https://github.com/XeroAPI/xero-ruby/blob/master/LICENSE)
 
-## 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)
+For questions that aren’t related to SDKs please refer to our [developer support page](https://developer.xero.com/support/).