mt-link-javascript-sdk/docs/README.md at master · mt-rsobachi/mt-link-javascript-sdk

Installation

Install the SDK using npm or yarn.

npm install @moneytree/mt-link-javascript-sdk

# or

yarn add @moneytree/mt-link-javascript-sdk

Then you can use it directly in your code:

Usage:

// using import
import mtLinkSdk, { MtLinkSdk } from '@moneytree/mt-link-javascript-sdk';

// or using require
const { default: mtLinkSdk, MtLinkSdk } = require('@moneytree/mt-link-javascript-sdk');

// or via window object
const instance = window.mtLinkSdk;
const newInstance = new window.MtLinkSdk();

// mtLinkSdk - an instance of the SDK.
// MtLinkSdk - in case you need to create a new instance of the SDK for whatever reason,
//             e.g: const newInstance = new MtLinkSdk();

Typscript

The source also includes Typescript definitions out of the box.

Polyfills

We use fetch and Promise internally, if you wish to support old browsers (e.g: IE11), make sure to add the necessary polyfills.

API

The Moneytree LINK Javascript SDK exposes APIs to get guest consent to access financial data, and exchange an authorization grant for an access token.

init

The init call is used to initialize the SDK and set default options for API calls. Some LINK APIs can be used without calling init.

Calls related to OAuth require a client id which can only be set via the init function. These APIs include:

authorize
onboard
exchangeToken
tokenInfo

Usage:

mtLinkSdk.init(clientId, options);

Parameter	Type	Required	Default Value	Description
clientId	string	true		OAuth `clientId` of the app (please request this from your Moneytree representative if you need one). NOTE: This function will throw an error if this parameter isn't provided.
options	object	false		These options include all of the values below and also all `options` parameters of the other APIs. Options values passed here during initialization will be used by default if no options are passed when calling a specific API. Available options are documented under authorize options and common options; refer to each individual link for more details.
options.mode	`production`, `staging`, `develop`, `local`	false	`production`	Environment for the SDK to connect to, the SDK will connect to the Moneytree production server by default. Moneytree clients should use `staging` for development as `develop` may contain unstable features. `local` should only be used for SDK development as it has local dependencies.
options.locale	string	false	Auto detect.	Force Moneytree to load content in this specific locale. A default value will be auto detected based on guest langauges configurations and location if available. Check this spec for more information. Currently supported values are: `en`, `en-AU`, `ja`.
options.cobrandClientId (private)	string	false		NOTE: This is an internal attribute. Please do not use it unless instructed by your integration representative. Brand Moneytree apps with client's branding. E.g: logo or theme.

authorize

OAuth authorization method to request guest consent to access data via the Link API.

For security reasons we removed support for implicit flow. We have opted for the PKCE/code grant flow.

Guest login is required for this SDK to work, by default we will show the login screen and redirect the guest to the consent screen after they log in (Redirection happens immediately if they are currently logged in; you may pass the forceLogout option to force the guest to log in, even if they have an active session.)

You may also choose to display the sign up form by default by passing the authAction option.

NOTE: You must initialize the SDK (via the init method) before calling this API.

Usage:

mtLinkSdk.authorize(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters as described in common options.
options.scopes	string OR string[]	false	Value set during `init`. OR `guest_read`	Access scopes you're requesting. This can be a single scope, or an array of scopes. Currently supported scopes are: `guest_read`, `accounts_read`, `points_read`, `point_transactions_read`, `transactions_read`, `transactions_write`, `expense_claims_read`, `categories_read`, `investment_accounts_read`, `investment_transactions_read`, `notifications_read`, `request_refresh`, `life_insurance_read`.
options.redirectUri	string	false	Value set during `init`.	OAuth redirection URI, refer here for more details. NOTE: This function will throw an error if this value is undefined and no default value was provided in the init options.
options.state	string	false	Value set during `init`. OR Randomly generated uuid.	Refer here for more details. NOTE: Make sure to set this value explicitly if your server generates an identifier for the OAuth authorization request so that you can use to acquire the access token after the OAuth redirect occurs.
options.codeChallenge	string	false		We only support SHA256 as code challenge method, therefore please ensure the `code_challenge` was generated using the SHA256 hash algorithm. Click here for more details. NOTE: Set this value only if your server wish to use PKCE flow.
options.pkce	boolean	false	false	Set to `true` if you wish to use PKCE flow on the client side, SDK will automatically generate the code challenge from a locally generated code verifier and use the code verifier in exchangeToken.
options.forceLogout	boolean	false	`false`	Force existing guest session to logout and call authorize with a clean state.

onboard

The onboard API allows a new guest to get onboard faster without having to go through the registration process. All you have to do is provide an emai address and pass the same options parameter as the authorize function. We will display a consent screen explaining the access requests and applicable scopes. Once the guest consents, a new Moneytree account will be created on their behalf and authorization is completed. Resulting behavior will be the same as the authorize redirection flow.

Onboard will force any current guest session to logout, hence you do not have to call logout manually to ensure a clean state.

If an account with this email address already exists we will redirect the guest to the login screen.

NOTE:

You must call `init` before using this API.

For legal reasons, you will have to set up your app's terms and conditions link to use the onboard API. Please ask your Moneytree representative for more details.

Usage:

mtLinkSdk.onboard(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters. Most options are the same as the authorize method options and common options with a few exceptions. Unsupported options from authorize and common options are: forceLogout authAction showAuthToggle showRememberMe
options.email	string	true	Value set during `init`.	A new Moneytree account will be created with this email address. If an existing account with this email exists, the guest will be redirected to the login screen. NOTE: SDK will throw an error if both values here and from the init options are undefined.

exchangeToken

Since we are using PKCE/Code grant, we will have to exchange the code for a token. You can optionally pass code via options parameter or it will fallback to automatically extract it from the browser URL.

code will be invalidated (can be used only once) after exchanged for a token, it is your responsibility to store the token yourself as the SDK does not store it internally.

Refer here for more details.

Usage:

One way to use this API is by calling it in the script on your redirection page. For example, if authorize redirects to https://yourapp.com/callback?code=somecode, you can call this function in the script loaded on that redirection page and the client library will automatically extract the code to exchange for a token.

Alternatively, you can extract the code manually from the redirect URL and pass it to this function via the options object yourself.

const token = await mtLinkSdk.exchangeToken(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters.
options.code	string	false	Value from browser URL	Code from OAuth redirection used to exchange for a token, SDK will try to extract it from the browser URL if none is provided. NOTE: SDK will throw an error if no value is provided here and the client library failed to extract it from browser URL.
options.codeVerifier	string	false		If you pass a `codeChallenge` option during the `authorize` or `onboard` call and wish to exchange the token on the client side application, make sure to set the code verifier used to generate the said `codeChallenge` here.
options.redirectUri	string	false	Value set during `init`.	Make sure the value of `redirectUri` here is the same redirectUri value used during the `authorize` or `onboard` call. NOTE: The SDK will throw an error if both this parameter and the default value from the init options are undefined.

tokenInfo

You can validate a token or get guest or resource server information related to the token by calling this API.

NOTE: This function will throw an error if the token has expired.

Usage:

const tokenInfo = await mtLinkSdk.tokenInfo(token);
tokenInfo.iat; // token creation timestamp,
tokenInfo.exp; // token expiration timestamp,
tokenInfo.sub; // guest uid or null,
tokenInfo.scope; // string with space separated scopes
tokenInfo.client_id; // application client id or null
tokenInfo.app; // application related information or null
tokenInfo.app.name; // application name
tokenInfo.app.is_mt; // is moneytree client (internal usage)
tokenInfo.guest; // guest related information or null
tokenInfo.guest.email; // guest email if available
tokenInfo.guest.country; // guest country
tokenInfo.guest.currency; // guest currency,
tokenInfo.guest.lang; // guest language

Parameter	Type	Required	Default Value	Description
token	string	true		Token you wish to get info for.

logout

Logout current guest from Moneytree.

Usage:

mtLinkSdk.logout(options);

Parameter	Type	Required	Default Value	Description
options	object	false	Value set during `init`.	Optional parameters. Includes all options in common options.

openService

This is a method to open various services provided by Moneytree such as Moneytree account settings, Vault etc.

NOTE: calling this API before calling init will open the services view without branding (company logo etc.)