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.
• sameWindow - Optional. Boolean. Default: false. If set to true, then the SDK will replace the current window/tab's location with the Truto Connect UI URL. Use this along with the redirect_uri option while creating a Link Token to redirect the user back to your application after the connection is successful. This option is also helpful when your end users are using a privacy-focused browser that blocks popups, iframes, etc.
• preventDeselect - Optional. Object. Default: empty. Used in RapidForm. If using multi select fields, it allows you to prevent the customer from unselecting the previously selected values in the RapidForm. Accepts value in the following format,

  {
    "field_name_1": {
        "message": "Reason for allowing deselection of values"
    },
    "field_name_2": ...
  }

• disabledFields - Optional. Object. Default: empty. Used in RapidForm. Allows you to disable fields in the RapidForm. Accepts value in the following format,

  {
    "field_name_1": {
        "message": "Reason for disabling the field"
    },
    "field_name_2": ...
  }

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.
• rapid_form_error - Occurs when you are trying to open a RapidForm. It could happen for various reasons, the most common error messages and causes are listed below -
  • RapidForm is not setup. - When there is no RapidForm setup for the integration.
  • The integrated account's token is not valid or has expired. Please generate a new token before retrying - https://truto.one/docs/api-reference/admin/integrated-accounts/create-token. - When the integrated_account_token that you generated has expired or is invalid.
  • There was an error fetching the resources for the fields in the RapidForm: <message> - When there was an error fetching the resources configured for the fields. The message will give you more details about the error.
  • Integrated account is not in the active state. Please reauth the integrated account. - When the integrated account is not in the active state. You can re-authenticate the integrated account to make it active.