@wealthica/wealthica.js v0.0.21

wealthica.js

Extend Wealthica by writing your own add-ons and widgets.

Wealthica is an aggregation platform that allows investors to see all their investments in a single Dashboard and get an unbiased view of their wealth. Each day, Wealthica connects to your financial institutions and retrieves accounts balances, positions and transactions. Wealthica is the largest financial aggregator in Canada with support for 60+ Canadian financial institutions and investment platforms.

This library provides the wrappers needed to setup the communication between the Wealthica Dashboard and 3rd-party add-ons. It aims to be simple to use and allows anyone with basic knowledge of JavaScript to write their own add-on.

Not sure where to start? Take a look at the Example Add-on code and see the instructions below to load it into your Wealthica Dashboard.

Ready to publish your add-on to the Wealthica Add-ons store? Contact us.

Financial Institutions

Wealthica supports connecting to the following Canadian financial institutions and investment portals. Support for importing positions (holdings), transactions and account statements varies. Visit our website for the most recent list of supported institutions.

• AGF
• Aligned Capital Partners
• Assante
• BMO InvestorLine
• BMO adviceDirect
• BMO Nesbitt Burns
• Canaccord Genuity
• CIBC Investor's Edge
• CIBC Wood Gundy
• Computershare Employee Online
• Computershare Exempt Market (Private Capital Investor)
• Credential Asset Management
• Cumberland Private Wealth
• Desjardins Valeurs Mobilières (VMD)
• Desjardins Courtage en Ligne (Disnat)
• Desjardins Private Wealth (GPD)
• Desjardins Insurance Retirement (DFS GRS)
• Desjardins Financial Security (DFS Investments)
• SFL Investments (Desjardins)
• Echelon Wealth Partners
• EdgePoint Wealth Management
• Épargne Placement Québec
• EQ Bank
• Fidelity Investments Canada
• Fondaction CSN
• Fonds de solidarité FTQ
• Gestion FÉRIQUE
• Great-West Group Retirement (GRS)
• Hampton Securities
• Harbourfront Wealth Management
• HollisWealth
• HSBC InvestDirect
• Industrial Alliance Financial Group
• Industrial Alliance Investia
• Industrial Alliance Securities
• Interactive Brokers
• Investors Group (IG Wealth Management)
• IPC Investment
• IPC Securities
• Laurentian Bank Direct Brokerage
• Manulife Group Retirement (GRS)
• Manulife VIP Room (previously Standard Life)
• Manulife Securities
• MD Financial Management
• National Bank Independent Network (NBIN and NBCN)
• National Bank Direct Brokerage
• National Bank Financial
• National Bank Private Banking 1859
• National Bank Trust
• Nest Wealth
• Qtrade Investor
• Quadrus
• Questrade
• Raymond James
• RBC Direct Investing
• RBC Dominion Securities
• Scotia iTrade
• Sun Life Financial
• Tangerine
• TD Direct Investing
• TD Waterhouse
• Virtual Brokers
• WealthBar
• Wealthsimple
• Wellington-Altus Private Wealth

Getting started

1. Login to your Wealthica.
2. Install the Developer Add-on. After that you will be redirected to the Developer Add-on page.
3. Click on the button next to the page title to open the Configure modal.
4. Enter https://wealthica.github.io/wealthica.js/example.html to the Add-on URL field and click Load to load the Example Add-on.
5. Try some of the sample actions provided in the add-on.

After trying out the Example Add-on, it's time to make your own add-on:

1. Clone Example Add-on or create your own add-on page.
2. From Wealthica navigate to the Developer Add-on and open the Configure modal and load your add-on.
3. Take a look at the APIs section below and start writing your add-on.

For a more advanced example, take a look at our Wealthica Cryptos Addon code.

Installation

npm install @wealthica/wealthica.js --save

Then include this in your add-on page:

<script src="/path/to/dist/addon.min.js"></script>

APIs

class: Addon

The Addon class is intended to be used by add-ons to setup their side of communication.

new Addon(options)

var addon = new Addon({
  // (optional) The 'id' of the add-on / widget.
  // This is only required in the add-on release preparation process.
  // For add-on development with the Developer Add-on, this should not be set.
  id: 'addon-id' | 'addon-id/widgets/widget-id'
});

event: 'init'

Emitted when Wealthica Dashboard has finished setting up the communication on its side. At this time add-on should use the passed-in options (filters, language, etc.) to finalize its rendering.

addon.on('init', function (options) {
  console.log(options);
  // {
  //   fromDate: '2018-01-01',
  //   toDate: '2018-04-30',
  //   language: 'en',
  //   privateMode: false,
  //   data: { preferredCurrencies: ['USD', 'CAD', 'GBP'] },
  //   ...
  // }
});

event: 'reload'

Emitted when there are important changes in Wealthica Dashboard (e.g. user has just added a new institution, or removed an asset). This suggests add-ons reload their data and render accordingly.

addon.on('reload', function () {
  // Start reloading
});

event: 'update'

Emitted when user updates one of the Dashboard filters. The Dashboard provides common filters including groups, institutions or date range filters. In response add-on should update itself according to received options.

addon.on('update', function (options) {
  // Update according to the received options
});

addon.addTransaction(attrs)

This method opens the Add Transaction form on the Dashboard and waits for user to submit the transaction or to close the modal. Pass an optional attrs object to pre-populate the transaction form. The newTransaction parameter is provided when a new transaction has been created.

addon.addTransaction({ description: "Some description" }).then(function (newTransaction) {
  // The form has been closed

  if (newTransaction) {
    // A new transaction has been created
  } else {
    // Nothing changed
  }
}).catch(function (err) {

});

addon.editTransaction(id)

This method opens the Edit Transaction form on the Dashboard and waits for user to update the transaction or to close the form. The updatedTransaction parameter is provided when the transaction has been updated.

addon.editTransaction('transaction-id').then(function (updatedTransaction) {
  // The form has been closed

  if (updatedTransaction) {
    // The transaction has been updated
  } else {
    // Nothing changed
  }
}).catch(function (err) {

});

addon.addInstitution(attrs)

This method opens the Add Institution form on the Dashboard and waits for user to finish the process or to close the form.

Pass an optional institution object ({ type, name }) to go straight to the institution's credentials form. Otherwise the modal will open at the Select Institution step.

The newInstitution parameter is provided when a new institution has been created.

addon.addInstitution({ type: 'demo', name: 'Demo' }).then(function (newInstitution) {
  // The form has been closed

  if (newInstitution) {
    // A new institution has been created
  } else {
    // Nothing changed
  }
}).catch(function (err) {

});

addon.addInvestment()

This method opens the Add Investment form on the Dashboard and waits for user to finish the process or to close the form.

addon.addInvestment().then(function (result) {
  // The form has been closed

  if (result) {
    // A new institution, asset or liability has been created
  } else {
    // Nothing changed
  }
}).catch(function (err) {

});

addon.editInstitution(id), addon.editAsset(id) & addon.editLiability(id)

These methods open the corresponding Edit form (Institution/Asset/Liability) on the Dashboard and wait for user to update the item or to close the form.

The updatedItem parameter is provided when the item has been successfully updated.

addon.editInstitution('institution-id').then(function (updatedItem) {
  // The form has been closed

  if (updatedItem) {
    // The item has been updated
  } else {
    // Nothing changed
  }
}).catch(function (err) {

});

addon.deleteInstitution(id), addon.deleteAsset(id) & addon.deleteLiability(id)

These methods open the corresponding Delete form (Institution/Asset/Liability) on the Dashboard and wait for user to confirm or to close the form.

The deleted parameter is provided when the item has been successfully deleted.

addon.deleteInstitution('institution-id').then(function (deleted) {
  // The form has been closed

  if (deleted) {
    // The item has been deleted
  } else {
    // Nothing changed
  }
}).catch(function (err) {

});

addon.downloadDocument(id)

This method triggers download of a Wealthica document

addon.downloadDocument('document-id').then(function () {
  // The action has been successfully carried out.
}).catch(function (err) {

});

addon.getSharings()

This method request the list of sharings for the logged in user.

NOTE: Only available for addons with "switch_user" feature flag.

addon.getSharings().then(function (sharings) {}).catch(function (err) {});

addon.switchUser(id)

This method switches Dashboard to viewing the user with provided id.

NOTE: Only available for addons with "switch_user" feature flag.

addon.switchUser(id).then(function () {
  // Successfully switched
}).catch(function (err) {});

addon.saveData(data)

This method allows add-on to persist data to the Wealthica user preferences. You can use this method to persist user configuration options. The add-on will receive this data under the data options parameter the next time it is initialized. Each add-on can store up to 100 KB of data (plus 4 KB per widget). Please note data is stored unencrypted in our database and may not be suitable for storing sensitive information.

addon.saveData({ preferredCurrencies: ['CAD', 'USD', 'GBP', 'MXN'] }).then(function () {

}).catch(function (err) {

});

API helpers

These are helper functions for requesting API calls. See our API docs for the full list of API endpoints, their parameters and what they do.

For API endpoints that are not yet supported by the API helpers, see addon.request in the Debug section below.

addon.api.getAssets(query)

addon.api.getAssets({ date: '2018-01-01' })
  .then(function (response) { }).catch(function (err) { });

addon.api.getCurrencies(query)

addon.api.getCurrencies({ from: '2018-01-01', to: '2018-01-31' })
  .then(function (response) { }).catch(function (err) { });

addon.api.getInstitutions(query)

addon.api.getInstitutions({ date: '2018-01-01' })
  .then(function (response) { }).catch(function (err) { });

addon.api.getInstitution(id)

addon.api.getInstitution('institution-id')
  .then(function (response) { }).catch(function (err) { });

addon.api.pollInstitution(id, version)

addon.api.pollInstitution('institution-id', 1)
  .then(function (response) { }).catch(function (err) { });

addon.api.syncInstitution(id)

addon.api.syncInstitution('institution-id')
  .then(function (response) { }).catch(function (err) { });

addon.api.addInstitution(data)

addon.api.addInstitution({
  name: 'Demo',
  type: 'demo',
  credentials: { username: 'wealthica', password: 'wealthica' }
}).then(function (response) { }).catch(function (err) { });

addon.api.getLiabilities(query)

addon.api.getLiabilities({ date: '2018-01-01' })
  .then(function (response) { }).catch(function (err) { });

addon.api.getPositions(query)

addon.api.getPositions({ groups: 'id1,id2', institutions: 'id1,id2' })
  .then(function (response) { }).catch(function (err) { });

addon.api.getTransactions(query)

addon.api.getTransactions({ groups: 'id1,id2', institutions: 'id1,id2' })
  .then(function (response) { }).catch(function (err) { });

addon.api.updateTransaction(id, attrs)

addon.api.updateTransaction('id', { currency_amount: 123 })
  .then(function (response) { }).catch(function (err) { });

addon.api.getUser()

addon.api.getUser().then(function (response) { }).catch(function (err) { });

Debug

event: 'postMessage'

Emitted every time the add-on posts a message to the Wealthica Dashboard.

addon.on('postMessage', function (origin, message) {
  console.log(arguments);
});

Emitted every time the add-on receives a message from the Wealthica Dashboard.

addon.on('gotMessage', function (origin, message) {
  console.log(arguments);
});

addon.request(options)

This is used to make a request to API endpoints that are not currently supported by addon.api.

addon.request({
  method: 'GET',
  endpoint: 'positions',
  query: {
    institutions: 'id1,id2',
    assets: true,
  }
}).then(function (response) { }).catch(function (err) { });

addon.setEffectiveUser(id)

This is used make addon.request() calls on behalf of another user who has shared access to the currently logged in user. It has the same effect for any of the addon.api helpers which are wrappers around addon.request().

addon.setEffectiveUser(userA);
addon.request({...}).then(function (response) { }).catch(function (err) { });

addon.setEffectiveUser(userB);
addon.request({...}).then(function (response) { }).catch(function (err) { });

// It's advised to clear effectiveUser after finishing on-behalf calls
addon.setEffectiveUser(null);
addon.request({...}).then(function (response) { }).catch(function (err) { });

Development

Install

yarn install

Build

yarn build

Test

yarn build
yarn test

Release

npm version patch # or minor/major
git push --tags
# wait until merged then
npm publish