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' }
  })
  .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' }
  })
  .catch((error) => {
    console.log(error);
  });

Options

The authenticate method accepts these options as the second argument:

Option	Type	Description
`integration`	`string`	Pre-select an integration, skipping the selection screen
`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
`iframe`	`boolean`	Show connection UI inside an iframe (default: `true`)
`additionalContext`	`object`	Stored under the `context` attribute of the integrated account
`integrations`	`string[]`	Limit which integrations are shown
`sameWindow`	`boolean`	Replace the current window instead of opening a popup (default: `false`)
`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 | post_install_error | validation_error",
  "integration": "integration name",
  "integrated_account_id": "integrated account id"
}

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 (e.g., OAuth failure)
`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

Native File Pickers

Show vendor-native file picker UIs for cloud storage integrations.

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.

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);
});