xero-node (alpha)

An API wrapper for xero (http://developer.xero.com).

Supports the three applications types:

Private - apps connecting to a single Org
Public - apps that connect to any Org, but with a 30 minute limitation
Partner - approved apps that can automatically refresh Org tokens

For any suggestions create a github issue, or fork the code and submit a PR.

Features

The following Xero API functions are supported:

Accounts
Attachments
Bank Transactions
Bank Transfers
Branding Themes
Contacts
Contact Groups
Credit Notes
Currencies
Employees
Expense Claims
Invoices
Invoice Reminders
Items
Journals
Manual Journals
Organisations
Payments
Purchase Orders
Receipts
Repeating Invoices
Reports
Tax Rates
Tracking Categories (and Tracking Options)
Users

The following endpoints are included but are not currently under test nor are they supported for use:

Timesheets (Payroll API)
Employees (Payroll API)
PayItems (Payroll API)

The following features are provided:

Create / Read / Update / Delete (for most endpoints)
Search (using 'where' clause)
Efficient pagination with callbacks
Support for Private, Public, and Partner applications (check out the sample app https://xero-sample-app.herokuapp.com for 3 legged oauth example)

Usage

This package can be installed via npm or yarn.

npm install --save xero-node

yarn add xero-node

Config Parameters

Parameter	Description	Mandatory
userAgent	The useragent that should be used with all calls to the Xero API	True
consumerKey	The consumer key that is required with all calls to the Xero API.,	True
consumerSecret	The secret key from the developer portal that is required to authenticate your API calls	True
authorizeCallbackUrl	The callback that Xero should invoke when the authorization is successful.	False
privateKeyPath	The filesystem path to your privatekey.pem file to sign the API calls	False
runscopeBucketId	Your personal runscope bucket for debugging API calls	False
redirectOnError	Whether the Xero Auth process should redirect to your app in the event the user clicks 'Cancel'	False

//Sample Private App Config
{
    "userAgent" : "REPLACE ME",
    "consumerKey": "AAAAAAAAAAAAAAAAAA",
    "consumerSecret": "BBBBBBBBBBBBBBBBBBBB",
    "privateKeyPath": "/some/path/to/privatekey.pem",
    "runscopeBucketId" : "xxxyyyzzzz"
}

//Sample Public App Config
{
    "userAgent" : "REPLACE ME",
    "consumerKey": "AAAAAAAAAAAAAAAAAA",
    "consumerSecret": "BBBBBBBBBBBBBBBBBBBB",
    "authorizeCallbackUrl": 'https://www.mywebsite.com/xerocallback',
    "runscopeBucketId" : "xxxyyyzzzz",
    "redirectOnError" : true
}

//Sample Partner App Config
{
    "userAgent" : "REPLACE ME",
    "consumerKey": "AAAAAAAAAAAAAAAAAA",
    "consumerSecret": "BBBBBBBBBBBBBBBBBBBB",
    "authorizeCallbackUrl": 'https://www.mywebsite.com/xerocallback',
    "privateKeyPath" : "/some/path/to/partner_privatekey.pem",
    "runscopeBucketId" : "xxxyyyzzzz",
    "redirectOnError" : true
}

Note: RunscopeBucketId has been added to support debugging the SDK. Runscope is a simple tool for Testing Complex APIs. You can use Runscope to verify that the structure and content of your API calls meets your expectations.

Sign up for a free runscope account at http://runscope.com and place your bucket ID in the config file to monitor API calls in real time.

Runscope is not endorsed by or affiliated with Xero. This tool was used by the SDK creator when authoring the code only.

App Usage

const xero = require('xero-node');
const fs = require('fs');
const config = require('/some/path/to/config.json');

//Private key can either be a path or a String so check both variables and make sure the path has been parsed.
if (config.privateKeyPath && !config.privateKey) 
    config.privateKey = fs.readFileSync(config.privateKeyPath);

// Available application types are:
// xero.PrivateApplication
// xero.PublicApplication
// xero.PartnerApplication

const xeroClient = new xero.PrivateApplication(config);

Examples

Sample app using this package: https://github.com/XeroAPI/xero-node-sample-app

Print a count of invoices:

//Print a count of invoices
xeroClient.core.invoices.getInvoices()
.then(invoices => {
    console.log("Invoices: " + invoices.length);
}).catch(err => {
    console.log(err);
});

Print the name of some filtered contacts:

//Print the name of a contact
xeroClient.core.contacts.getContacts({ 
    where: 'Name.Contains("Bayside")' 
})
.then(contacts => {
    contacts.forEach(contact => {
        console.log(contact.Name);
    });
}).catch(err => {
    console.log(err);
});

Efficient paging:

/* Called per page */
const onContacts = (err, response, cb) => {
    let contacts = response.data;
    if (response.finished) // finished paging
        ....
    cb(); // Async support
};

xeroClient.core.contacts.getContacts({ pager: {start:1 /* page number */, callback: onContacts}})
    .catch(err => {
        console.log(`Oh no, an error: ${err}`);
    });

Filter support: Modified After

// No paging
xeroClient.core.contacts.getContacts({ 
    modifiedAfter: new Date(2013,1,1) 
})
.then(contacts => {
    contacts.forEach(contact => {
        // Do something with contact
    });
})

Docs

Check the docs folder for more detailed examples of how to use each SDK function.

Tests

yarn test

Roadmap

Feel free to send PRs on any of these issues.

Release Change Log

2.9.0
- Merged PR#98 - Add support for redirectOnError
~~2.7.0~~ Released as 2.8.0
- Merged PR#84 - Add support for Employees
- Merged PR#85 - Fix for BankTransactions
- Merged PR#88 - Add support for Receipts' Endpoint
- Merged PR#89 - Fix issue for Tracking Categories
- Merged PR#90 - Add support for Expense Claims
- Merged PR#92 - Add support for Purchase Orders
- Merged PR#94 - Issue 87
2.6.0
- Merged PR#79 - Add support for ContactGroups
- Merged PR#80 - Fixes Contact address deatil schema.
2.5.3
- Merged PR#76 - Updated the docs to add repeating invoices (missed from PR#72).
- Merged PR#75 - Added documentation about invoice/contact filters.
2.5.2
- Merged PR#72 - Fix for Issue#71 to add support for the repeating invoices endpoint.
- Merged PR#70 - Fix for Issue#69 where oauth errors were not being serialised to JSON.
2.5.1
- Merged PR#68 - Fix for Issue#67 where attachments with an '&' in the name couldn't be downloaded.
2.5.0
- Merged PR#65 - Removed xml2js and instead use only application/json as a content-type.
- Refactored e2e tests to be modular and easier to maintain
- Fixed various linting and code styling issues
- Updated extend.js to latest version of Backbone
- Updated Date variables in all schemas to be Date Objects instead of strings.
2.4.0
- Merged PR#64 - Updated accountingtests.js to pass ESlint rules.
- Merged PR#63 - Add style guide and ESlint check.
- Merged PR#61 - Add roadmap to readme.
- Merged PR#59 - Remove log4js dependency. Uses console.log instead.
2.3.0
- Removed the sample application as there was an issue with clashing dependencies. This has been moved to a separate repo: xero-node-sample-app
- Merged PR#58 - Fix lodash require issue.
- Merged PR#57 - Give xml2js a version in package.json
- Merged PR#56 - Update docs issue in Payments.md.
2.2.2
- Merged PR#55 - Fixed webpack warning.
- Merged PR#53 - Updated log4js.
- Merged PR#51 - Moved unecessary dependencies into dev dependencies.
2.2.1
- Merged PR#49 - Merge PR#49 to change createPayment method to be newPayment in line with other entities, and introduce a new savePayments method for creating multiple payments in one call.
2.2.0
- Merged PR#46 - Merge PR#45 and provide library level support for boolean values (formerly this required string conversion).
2.1.8
- Merged PR#44 - Merge PR#43 and expose more contact fields (fix for issue #40).
2.1.7
- Merged PR#41 - Added support for multiple item creation (fix for issue #39).
2.1.6
- Merged PR#38 - Fixed attachment streaming bug on partner applications.
2.1.5
- Merged PR#34 - Updated lodash version as this was causing minor issues.
2.1.4
- Merged PR#24 - Add support for Manual Journals.
2.1.3
- Merged PR#18 - set a default useragent header when not provided in the config file and warn the user.
2.1.2
- Merged PR#17 - fix typo.
2.1.1
- Merged PR#16 - fix typo.
2.1.0
- Added support for adding Attachments to Accounts, BankTransactions, BankTransfers, Contacts, CreditNotes and Invoices
- Fixed issues in the readme.
2.0.2
- Merged changes from PR#10 which fixes an issue where errors were being swallowed.
2.0.1
- Updated readme to reference npm availability.
2.0.0
- Updated package for NPM deployment. Jump to v2.0.0 under advise of NPM.
0.0.4
- view Externalised the config file for private apps, fixed the log level settings, updated the tests to use 'should' library, added support for runscope urls within the signature generation
- view updated readme
- view updated tests to check each field of an account
- view added account tests. Currently there is an issue creating new accounts: BankAccountNumber is not being sent through. Needs investigation
- view added more tests for accounts. Fixed bug around passing BankAccountNumbers. TODO: Delete method hasn't been implemented globally.
- view added support for Payments, however this is still in progress.
- view fixed bug with payments, these are working as expected
- view updated banktransactions to copy contact objects from XML correctly
- view removed guid from test
- view changed tests to all running
- view added support for invoice rounding
- view updated DP rounding fix to remove double querystring additions
- view added support for externalising user-agent header in config.json file
- view added zombie support to gain access tokens on public apps
- view added support for istanbul test reporting, and completed support for public app auth
- view fixed issue with banktransfers fromXML function, updated tests to pass above 80%
- view fixed tests for contacts and added more address information to the schema
- view updated items to support retrieving and saving
- view updated various elements to have consistent responses on when save() is called. Updated Items tests to have 100% coverage.. woohoo
- view externalised the runscope bucket ID to the config file
- view fixed the saveContacts method on the contacts object and did some refactoring. This concept could be applied across all endpoints. Also removed some console.log statements from the code
- view added tests for Journals
- view added payment tests
- view added support for tracking categories but tracking options is not currently working
- view added support for tracking categories and tracking options
- view Added attachment Tests but these aren't currently working
- view Updated readme
- view updated readme
- view added support for Partner application types
- view updated sample app to get this working
- view Updated tests to override the default callback URL
- view Updated the sample app to use a bootstrap theme.
- view Added more support for features in the sample app
- view Added support for the remaining endpoints to sample app
- view Added navigation highlights
- view Updated oauth_test to sample_app
- view Merge pull request #3 from jordanwalsh23/v1.0.0
- view added various tests and updated sample app
- view Merge pull request #4 from jordanwalsh23/v1.0.0
- view updated tests
- view adding tax rates
- view Reflect the fact that issues are switched off
- view Reflect deprecation of entrust certs
- view Merge pull request #5 from davidbanham/no-issue
- view Change user-specific config paths
- view Move config setup to before hook
- view Increase timeout for token tests
- view Drop org selection
- view updated gitignore to ignore *config.json files
- view Merge branch 'master' of github.com:jordanwalsh23/xero-node
- view Merge pull request #6 from davidbanham/deprecate-entrust
- view Merge branch 'master' of github.com:jordanwalsh23/xero-node
- view Explain test failure for tax rates get test
- view Fix reference to undefined obj
- view Throw errors instead of objects.
- view fixing taxrates
- view Merge pull request #7 from davidbanham/fix-errors
- view Merge branch 'master' of github.com:jordanwalsh23/xero-node
- view fixed taxrates test
- view Add missing space to error message
- view Add account creation hooks to payment tests
- view Set timeout globally
- view Add account creation hooks to bank transaction testing
- view Use created bank accounts for bank transfers tests
- view Add setup and teardown of tracking categories for region test
- view Make accounts test repeatable
- view Unskip working tests
- view Unskip tax rate test after rebase
- view Merge branch 'davidbanham-refactor-tests'
- view s/fail/catch/g
- view Add entropy to updated name
- view Switch application.js to native Promises
- view Complete switch to native promises
- view Add editorconfig for 4 space tabs
- view Add yarn lockfile
- view Merge branch 'davidbanham-promises'
- view Merge branch 'meta' of git://github.com/davidbanham/xero-node into davidbanham-meta
- view Merge branch 'davidbanham-meta'
- view Pass config variables rather than reading file from disc.
- view Just use camelCase rather than PascalCase in passed config
- view s/_.extend/Object.assign/g
- view updated sample app to include taxrates and users
- view Merge branch 'config' of git://github.com/davidbanham/xero-node into davidbanham-config
- view updated sample app and removed console.log from taxrate
- view Merge branch 'davidbanham-config'
- view Merge branch 'less-lodash' of git://github.com/davidbanham/xero-node into davidbanham-less-lodash
- view migrated config files to their own directories
- view Merged dabvidbanhan-less-lodash
- view updated sample_app.js to index.js
- view removed comments from json file
- view working on refresh functions
- view implemented refresh function. Need to detect unauthorized API call and automatically refresh the tokens
- view added automatic refresh on the GET function, haven't tested it properly yet
- view added refresh and check expiry functions. Also updated the sample app
- view Minor cleanup of promise/callback confusion in tests
- view Merge branch 'davidbanham-cleaner-tests'
- view Merge branch 'master' into add_refresh_token_functionality
- view Added event emitter to send updated tokens.
- view merged promise/callback fix
- view fixed test file merge issue
- view added tax rates save and delete functions
- view updated yarn.lockfile
- view added the 'after' function to cleanup the test accounts
- view Merge pull request #18 from jordanwalsh23/accounts_setup_teardown_cleanup
- view re-added the tests after commenting them out
- view Merge pull request #17 from jordanwalsh23/add_taxrate_support
- view Merge branch 'master' into add_refresh_token_functionality
- view reverted forced timeout of the token
- view Merge branch 'add_refresh_token_functionality' of github.com:jordanwalsh23/xero-node into add_refresh_token_functionality
- view Merge pull request #14 from jordanwalsh23/add_refresh_token_functionality
- view merged from master
- view Drop events dep
- view adding recursion to reports parsing
- view Merge branch 'davidbanham-events'
- view Clean up ternary expressions
- view Clean up setOptions API
- view Remove catch statement for event handlers
- view added reports to the sample app, not yet completed
- view Merge pull request #20 from davidbanham/events
- view Merge branch 'master' into add_reports_endpoint_support
- view added reports view. Still has issues with rendering
- view Added support for 9 reports.
- view added support for retrieving branding themes
- view Merge pull request #21 from jordanwalsh23/add_reports_endpoint_support
- view merged from master
- view fixed require paths
- view Merge pull request #22 from jordanwalsh23/add_branding_themes
- view added currencies support
- view Merge pull request #23 from jordanwalsh23/add_currencies_support
- view added name and version to user-agent header
- view added support for retrieving invoice reminder settings
- view Merge pull request #25 from jordanwalsh23/add_invoice_reminders
- view Merge pull request #24 from jordanwalsh23/user_agent_modifier
- view added credit note support and refactored some methods
- view added support for credit notes and allocations
- view Merge pull request #26 from jordanwalsh23/add_credit_notes
- view updated readme and sample app. Removed payroll functions from sample app.
- view updated package.json
- view Merge pull request #27 from jordanwalsh23/prep_for_pr_to_master
- view Merge pull request #3 from jordanwalsh23/master
- view added function to allow users to set the log level
- view Merge pull request #28 from jordanwalsh23/externalise_log_level
- view updated readme
- view Merge branch 'master' of github.com:jordanwalsh23/xero-node
- view removed unecessary logging from test
- view Merge pull request #4 from jordanwalsh23/master
0.0.3
- Merged various orphan branches
0.0.2
- Added journals
- modifiedAfter support
0.0.1
- Initial Release

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jordanwalsh23 / xero-node