Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

xero-node

Package Overview
Dependencies
Maintainers
1
Versions
176
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

xero-node

Xero API Wrapper for all application types

  • 2.1.6
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
51K
decreased by-23.5%
Maintainers
1
Weekly downloads
 
Created
Source

xero-node (alpha)

npm version

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
  • Credit Notes
  • Currencies
  • Invoices
  • Invoice Reminders
  • Items
  • Journals
  • Manual Journals
  • Organisations
  • Payments
  • 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 (look at sample_app/index.js for 3 stage support)

Usage

This package can be installed via npm or yarn.

npm install --save xero-node

yarn add xero-node

Config Parameters

ParameterDescriptionMandatory
userAgentThe useragent that should be used with all calls to the Xero APITrue
consumerKeyThe consumer key that is required with all calls to the Xero API.,True
consumerSecretThe secret key from the developer portal that is required to authenticate your API callsTrue
AuthorizeCallbackUrlThe callback that Xero should invoke when the authorization is successful.False
privateKeyPathThe filesystem path to your privatekey.pem file to sign the API callsFalse
runscopeBucketIdYour personal runscope bucket for debugging API callsFalse

//Sample Private App Config
{
    "userAgent" : "Tester (PRIVATE) - Application for testing Xero",
    "consumerKey": "AAAAAAAAAAAAAAAAAA",
    "consumerSecret": "BBBBBBBBBBBBBBBBBBBB",
    "privateKeyPath": "/some/path/to/privatekey.pem",
    "runscopeBucketId" : "xxxyyyzzzz"
}

//Sample Public App Config
{
    "userAgent" : "Tester (PUBLIC) - Application for testing Xero",
    "consumerKey": "AAAAAAAAAAAAAAAAAA",
    "consumerSecret": "BBBBBBBBBBBBBBBBBBBB",
    "authorizeCallbackUrl": 'https://www.mywebsite.com/xerocallback',
    "runscopeBucketId" : "xxxyyyzzzz"
}

//Sample Partner App Config
{
    "userAgent" : "Tester (PARTNER) - Application for testing Xero",
    "consumerKey": "AAAAAAAAAAAAAAAAAA",
    "consumerSecret": "BBBBBBBBBBBBBBBBBBBB",
    "authorizeCallbackUrl": 'https://www.mywebsite.com/xerocallback',
    "privateKeyPath" : "/some/path/to/partner_privatekey.pem",
    "runscopeBucketId" : "xxxyyyzzzz"
}

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

var xero = require('xero-node');
var fs = require('fs');
var 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

var xeroClient = new xero.PrivateApplication(config);

Examples

Print a count of invoices:

//Print a count of invoices
xeroClient.core.invoices.getInvoices()
.then(function(invoices) {
    console.log("Invoices: " + invoices.length);
}).catch(function(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(function(contacts) {
    contacts.forEach(function(contact) {
        console.log(contact.Name);
    });
}).catch(function(err) {
    console.log(err);
});

Efficient paging:

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

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

Filter support: Modified After

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

Docs

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

Tests

npm test

Release Change Log

  • 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
  • 2.1.1
  • 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

Copyright (c) 2017 Tim Shnaider, Guillermo Gette, Andrew Connell, Elliot Shepherd, David Banham, and Jordan Walsh

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.

Keywords

FAQs

Package last updated on 19 Jun 2017

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc