Link SDK | Truto Documentation

@truto/truto-link-sdk is a browser SDK for connecting your customer's accounts to Truto. It provides the Truto Connect UI for account linking and RapidForm for post-connection data selection.

Try it live: The Truto Link SDK Playground lets you try Connect, File Picker, and RapidForm flows interactively — no setup required.

Installation

npm install @truto/truto-link-sdk

Truto Connect

To show the Truto Connect UI, generate a link-token via the Truto API from your backend server. See Create Link Token.

import authenticate from '@truto/truto-link-sdk';
 
const linkToken = 'link-token-uuid';
 
authenticate(linkToken, {})
  .then((response) => {
    console.log(response);
    // { result: 'success', integration: 'copper', integrated_account_id: '...', post_connect_form: '{}' }
  })
  .catch((error) => {
    console.log(error);
  });

RapidForm

To show the RapidForm, generate an integrated-account-token via the API. See Create Integrated Account Token.

import { rapidForm } from '@truto/truto-link-sdk';
 
const integratedAccountToken = 'integrated-account-token-uuid';
 
rapidForm(integratedAccountToken, {})
  .then((response) => {
    console.log(response);
    // { result: 'success', integration: 'copper', integrated_account_id: '...', post_connect_form: '{}' }
  })
  .catch((error) => {
    console.log(error);
  });

Options

Both authenticate and rapidForm accept these options as the second argument:

Option	Type	Description
`integration`	`string`	Pre-select an integration, skipping the selection screen
`iframe`	`boolean`	Show the UI in a full-screen iframe overlay on your page (default: `true`). Set to `false` to open a popup window instead
`sameWindow`	`boolean`	Navigate the current window to the Truto UI instead of opening an overlay or popup (default: `false`). The function then returns nothing, so there is no promise to await: the result arrives as query parameters on the link token's `redirect_uri`
`width`	`number`	Popup window width in pixels when `iframe` is `false` (default: `700`)
`height`	`number`	Popup window height in pixels when `iframe` is `false` (default: `800`)
`baseUrl`	`string`	Origin serving the Truto UI, for self-hosted or staging deployments (default: `https://app.truto.one`). Must be an absolute `http(s)` URL

authenticate also accepts:

Option	Type	Description
`noBack`	`boolean`	Hide the "Back" button on the connection screen
`authFormat`	`string`	Authentication format: `api_key`, `oauth2`, `oauth2_client_credentials`, `keka_oauth`
`skipRapidForm`	`boolean`	Skip the RapidForm UI after account connection
`integrations`	`string[]`	Limit which integrations are shown

rapidForm also accepts:

Option	Type	Description
`additionalContext`	`object`	Stored under the `context` attribute of the integrated account
`preventDeselect`	`object`	Prevent deselection of multi-select values in RapidForm
`disabledFields`	`object`	Disable specific fields in RapidForm

Error Handling

Errors follow this structure:

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

integrated_account_id is present only when the failure concerns an account that already exists: a re-authorization that was refused or failed, and post_install_error or validation_error after the account was created. A first connection that fails before the account exists, such as the user cancelling on the provider's consent screen, carries no integrated_account_id key at all. The same applies to the query parameters appended to a link token's redirect_uri.

Error Type	Description
`invalid_token`	The link token is invalid or expired
`invalid_integration`	Invalid or uninstalled integration name
`connection_error`	Error during the connection flow. When the provider refuses authorization, for example the user cancels on the consent screen, `error` carries the provider's own reason (`error_description` when the provider sends one, otherwise its error code, such as `access_denied`), truncated to 300 characters.
`app_credentials_not_configured`	The integration cannot be connected yet: its app credentials (your own OAuth app, or AWS STS signing credentials) are not configured in the environment. `error` carries the same string. In full-page mode the end user is shown who to contact; in iframe and popup modes the dialog closes, so show your own message. An admin fixes it under the integration's Configuration tab (see Overriding OAuth credentials).
`post_install_error`	Post-install steps failed after account creation
`validation_error`	Validation requests failed after account creation
`rapid_form_error`	Error opening or processing RapidForm

When the user closes the overlay or popup without finishing, the promise rejects with the string "closed" instead of an object. When the browser blocks the popup (iframe: false), it rejects with the string "blocked".

Native File Pickers

Show vendor-native file picker UIs for cloud storage integrations. showFilePicker accepts sharepoint, onedrive, googledrive (or google), box, dropbox and dropboxpersonal as the integration name. The pickers always talk to https://api.truto.one and do not read baseUrl.

SharePoint / OneDrive

import { showFilePicker } from '@truto/truto-link-sdk';
 
const integratedAccountToken = 'integrated-account-token-uuid';
 
showFilePicker('sharepoint', integratedAccountToken, {})
  .then((response) => {
    console.log(response);
  });

Google Drive

import { showFilePicker } from '@truto/truto-link-sdk';
 
showFilePicker('googledrive', integratedAccountToken, {
  appId: '1234567890',
  title: 'Choose Files',
  maxItems: 5,
  views: [
    { viewId: 'DOCS', includeFolders: true, selectFolderEnabled: true },
    { enableDrives: true, includeFolders: true },
  ],
}).then((response) => {
  console.log(response);
});

Box

Add your site's domain to the CORS Allowed Domains in your Box Developer Console.

showFilePicker('box', integratedAccountToken, {})
  .then((response) => console.log(response));

Dropbox

Add your site's domain to the Allowed Domains in your Dropbox Developer Console.

Use dropboxpersonal instead of dropbox for Dropbox personal accounts.

showFilePicker('dropbox', integratedAccountToken, {
  appKey: 'your-dropbox-app-key',
}).then((response) => console.log(response));

File Picker Transforms

Use trutoExpression (a JSONata expression) to transform picked items before they are stored:

showFilePicker('onedrive', integratedAccountToken, {
  trutoExpression: "$.($merge([{'selected_at': $now()}, $]))",
}).then((response) => {
  console.log(response);
});

Set truto_upsert_drive_items: true to merge new selections with existing items instead of replacing them:

showFilePicker('onedrive', integratedAccountToken, {
  truto_upsert_drive_items: true,
}).then((response) => {
  console.log(response);
});

For SharePoint and OneDrive, set truto_preselect_drive_items: true to open the picker with the items already stored on the integrated account selected:

showFilePicker('sharepoint', integratedAccountToken, {
  truto_preselect_drive_items: true,
}).then((response) => {
  console.log(response);
});