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.

Native File Pickers

Show Sharepoint's native file picker

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

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

showFilePicker(integrationName, integratedAccountToken, {})
  .then((response) => {
    console.log(response);
    // returns the selected items and stores them in the integrated account as the drive_items variable.
  })
  .catch((error) => {
    console.log(error);
  });

Show OneDrive's native file picker

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

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

showFilePicker(integrationName, integratedAccountToken, {})
  .then((response) => {
    console.log(response);
    // returns the selected items and stores them in the integrated account as the drive_items variable.
  })
  .catch((error) => {
    console.log(error);
  });

Show Google Drive's native file picker

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

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

// Minimal config (uses defaults)
const config = {
  appId: '1234567890', // Your Google Cloud project number
};

// Or with custom configuration
const customConfig = {
  appId: '1234567890',
  title: 'Choose Files',
  maxItems: 5,
  views: [
    {
      viewId: 'DOCS',
      includeFolders: true,
      selectFolderEnabled: true,
    },
    {
      enableDrives: true,
      includeFolders: true,
    },
  ],
};

showFilePicker(integrationName, integratedAccountToken, config)
  .then((response) => {
    console.log(response);
    // returns the selected items and stores them in the integrated account as the drive_items variable.
  })
  .catch((error) => {
    console.log(error);
  });

Show Box's native file picker

Make sure to add your site's domain to the CORS Allowed Domains in your OAuth App Configuration on Box Developer Console.

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

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

showFilePicker(integrationName, integratedAccountToken, {})
  .then((response) => {
    console.log(response);
    // returns the selected items and stores them in the integrated account as the drive_items variable.
  })
  .catch((error) => {
    console.log(error);
  });

Show Dropbox's native file picker

Make sure to add your site's domain to the Allowed Domains in your OAuth App Configuration on Dropbox Developer Console.

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

const integratedAccountToken = 'integrated-account-token-uuid';
const integrationName = 'dropbox'; // or 'dropboxpersonal' for personal accounts

const config = {
  appKey: 'your-dropbox-app-key',
};

showFilePicker(integrationName, integratedAccountToken, config)
  .then((response) => {
    console.log(response);
    // returns the selected items and stores them in the integrated account as the drive_items variable.
  })
  .catch((error) => {
    console.log(error);
  });

Config object schema

Sharepoint: The config object follows the same configuration schema that Microsoft's File Picker accepts. You can find the schema here. OneDrive: The config object follows the same configuration schema that Microsoft's File Picker accepts. You can find the schema here. Google Drive: The config object schema supports all Google Picker API options. Here's the complete schema with sample values:

{
  "enableFeature": ["MULTISELECT_ENABLED"],
  "disableFeature": "NAV_HIDDEN",
  "title": "Choose Your Files",
  "appId": "1234567890",
  "developerKey": "AIzaSyBvOkBvXANX...",
  "locale": "en-US",
  "maxItems": 10,
  "origin": "https://example.com",
  "selectableMimeTypes": ["image/jpeg", "image/png", "application/pdf"],
  "size": {
    "width": 800,
    "height": 600
  },
  "views": [
    {
      "viewId": "DOCS",
      "includeFolders": true,
      "selectFolderEnabled": true,
      "query": "important",
      "mimeTypes": "application/pdf"
    },
    {
      "enableDrives": true,
      "includeFolders": true,
      "selectFolderEnabled": true,
      "parent": "0ABC123xyz"
    }
  ]
}

Minimal example (using defaults):

{
  "appId": "1234567890"
}

This will use the default configuration:

• Title: "Select files"
• Multi-select enabled
• Two views: DOCS view and drives-enabled view

Box: The config object follows the same configuration schema that Box's Content Picker accepts. You can find the schema here

Dropbox: The config object follows the same configuration schema that Dropbox's File Picker accepts. appKey is the additional parameter that is required for Dropbox. You can find the schema here.

{
  "appKey": "string" //Required for Dropbox. This is the app key/client id for the Dropbox app.
}

Using trutoExpression in File Picker Config

You can use the trutoExpression property in the config object when calling file picker.

trutoExpression allows you to provide a JSONata expression that will be applied to the picked items before they are returned and stored. This is useful for transforming, filtering, or mapping the selected files/folders according to your needs.

Example usage:

const config = {
  trutoExpression: '$.($merge([{'selected_at': $now()}, $]))',
};

showFilePicker('onedrive', integratedAccountToken, config)
  .then((response) => {
    console.log(response); // The picked items will be transformed by the expression
  })
  .catch((error) => {
    console.log(error);
  });

This expression adds a timestamp field called selected_at to each selected item. This timestamp helps track when files were chosen. Additionally, you can use the date to modify or filter the selected items, giving you control over which items get synced in your Sync Jobs.

• The expression is evaluated on the array of picked items.
• The result of the expression is what will be returned from the promise and stored in the integrated account context.
• If you do not provide trutoExpression, the original picked items will be returned as-is.

For more about JSONata syntax, see the JSONata documentation.

Using truto_upsert_drive_items in File Picker Config

You can use the truto_upsert_drive_items property in the config object when calling file picker.

truto_upsert_drive_items is a boolean option that controls how selected items are stored in the integrated account context. When set to true, the newly selected items will be merged with existing drive_items in the integrated account context, rather than replacing them entirely.

Default behavior (replace mode):

• By default, when items are selected, they replace any existing drive_items in the integrated account context.

Upsert mode:

• When truto_upsert_drive_items is set to true, newly selected items are merged with existing items.
• Duplicate items (identified by their id field) are automatically deduplicated, keeping the most recent version.
• This is useful when you want to allow users to add more files over time without losing previously selected items.

Example usage:

// Replace mode (default) - new items replace existing ones
const replaceConfig = {
  trutoExpression: '$.($merge([{'selected_at': $now()}, $]))',
};

showFilePicker('onedrive', integratedAccountToken, replaceConfig)
  .then((response) => {
    console.log(response); // Only the newly selected items
  });

// Upsert mode - new items are merged with existing ones
const upsertConfig = {
  trutoExpression: '$.($merge([{'selected_at': $now()}, $]))',
  truto_upsert_drive_items: true,
};

showFilePicker('onedrive', integratedAccountToken, upsertConfig)
  .then((response) => {
    console.log(response); // Newly selected items merged with existing ones
  });

Notes:

• Items are deduplicated by their id field. If a newly selected item has the same id as an existing item, the new item will replace the old one in the merged result.
• The upsert operation works with both array and object formats of drive_items in the integrated account context.
• You can combine truto_upsert_drive_items with trutoExpression to transform items before they are merged.