@truto/truto-link-sdk

Truto Link SDK for the browser

This package allows you to connect your customer's accounts to your Truto account and also show the RapidForm after an integrated account is connected.

To show the Truto Connect UI, generate a link-token via the Truto API from your backend server. To know how to generate a link token, please refer to the Truto API documentation.

To show the RapidForm, generate an integrated-account-token via the Truto API from your backend server. To know how to generate an integrated account token, please refer to the Truto API documentation.

Installation

npm install @truto/truto-link-sdk
# yarn add @truto/truto-link-sdk

Usage

Open the Truto Connect UI

import authenticate from '@truto/truto-link-sdk';

const linkToken = 'link-token-uuid';
const options = {}; // refer Options section below

// authenticate opens a new window with the Truto Link UI, and returns a promise 
// which resolves after your customer has successfully connected their account.
// It rejects if the customer closes the window or if there was an error while connecting their account.

authenticate(linkToken, options).then((response) => {
  console.log(response);
  // { result: 'success', integration: 'copper' }
}).catch((error) => {
  console.log(error);
})

Open the RapidForm UI

import { rapidForm } from '@truto/truto-link-sdk';

const integratedAccountToken = 'integrated-account-token-uuid';

// rapidForm opens a new window with the RapidForm for the integrated account, and returns a promise 
// which resolves after your customer has successfully selects the data they need.
// It rejects if the customer closes the window or if there was an error while saving the selection.

rapidForm(integratedAccountToken, {}).then((response) => {
  console.log(response);
  // { result: 'success', integration: 'copper' }
}).catch((error) => {
  console.log(error);
})

Options

The authenticate method accepts the following options as the second argument.

• integration - Optional. String. The name of the integration you want to pre-select. This will skip the integration selection screen.
• noBack - Optional. Boolean. Prevents the "Back" button from appearing when viewing a specific integration connection screen. This helps in making sure that users only connect the integration you want them to.
• authFormat - Optional. String. The authentication format to be used when an integration supports multiple authentication flows. Can be api_key, oauth2, oauth2_client_credentials and keka_oauth. If not provided, then in case of the multi-auth integrations, the end-user can choose the authentication method to proceed with in the UI. This parameter is ignored in case of single auth integrations.
• skipRapidForm - Optional. Boolean. Skips the RapidForm UI after the account is connected. This is useful when you want to connect an account and then show the RapidForm UI later. You can use the rapidForm method to show the RapidForm UI later.
• iframe - Optional. Boolean. Default: true. Shows the connection UI inside an iframe.
• additionalContext - Optional. Object. Can be sent in rapidForm method as part of the options object. This object will be stored under the context attribute of the integrated account.
• integrations - Optional. Array of Strings. The integrations to show in the integration list and allow the customer to connect.

Errors

Something could always go wrong while connecting an account, so these are the possible errors you should handle. The error object will have the following structure,

{
  "result": "error",
  "error": "string describing the error",
  "error_type": "invalid_token | invalid_integration | connection_error | post_install_error | validation_error",
  "integration": "integration name",
  "integrated_account_id": "integrated account id"
}

integrated_account_id will be sent only if the error is post_install_error or validation_error.

Error types

• invalid_token - The link token is invalid or expired.
• invalid_integration - The integration name is invalid, has typo or is not installed in the environment.
• connection_error - There was an error while connecting the account. Usually happens when the OAuth flow fails.
• post_install_error - Occurs after the integrated account is created and when the post install steps setup for the integration fail.
• validation_error - Occurs after the integrated account is created and while running the validation requests setup for the integration fail.