Link SDK

@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:

authenticate also accepts:

rapidForm also accepts:

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.

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".

Styling the Connect UI

authenticate takes no styling options. The Connect UI's brand name, icon, consent terms, and custom CSS are set per environment under Settings → Branding in the Truto dashboard and apply to every connection that environment opens. Custom CSS targets thirteen data-truto-el elements, such as card and submit; load the Connect UI with ?custom_css=off to see it without your stylesheet. See Brand the Connect UI.

Embedded widgets

widgets.connections() mounts Truto's connections widget inline, inside an element you own, instead of as an overlay. It lists the integrations enabled in your environment and one tenant's connections, with whichever of Connect, Reconnect, Refresh, and Delete the environment allows. Your backend mints a session token for the tenant with POST /session-token, and the environment must list your page's origin under Settings → Connections widget → Allowed origins.

import { widgets } from '@truto/truto-link-sdk';
 
const widget = widgets.connections({
  container: document.getElementById('integrations'),
  environmentId: '<environment_id>',
  getToken: async () => {
    const response = await fetch('/api/truto/session-token', { method: 'POST' });
    return response.json(); // { session_token, expires_at }
  },
  onEvent: (e) => console.log(e.event, e.payload),
});
 
// On unmount, route change, or sign-out.
widget.destroy();

The widget has its own theme and custom CSS, separate from the Connect UI's. See Embed the connections widget for session tokens, every option and event, capabilities, and styling.

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