# Link SDK

> Source: https://truto.one/docs/sdks/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](https://playground.truto.one/) lets you try Connect, File Picker, and RapidForm flows interactively — no setup required.

## Installation

```bash
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](/docs/api-reference/admin/link-token/create).

```javascript
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](/docs/api-reference/admin/integrated-accounts/create-token).

```javascript
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:

```json
{
  "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

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

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

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

### Google Drive

```javascript
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.

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

### Dropbox

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

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

## File Picker Transforms

Use `trutoExpression` (a [JSONata](https://jsonata.org/) expression) to transform picked items before they are stored:

```javascript
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:

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