![\"Truto](\"https://frontsite-logos.truto.one/truto.svg\")
\n \n \n \n
\n Unified API for Everything
\n The integration platform that gives devs full control and sales the integrations they need to close deals now.\n
\n Website •\n Docs •\n Playground\n
\n\n---\n\n# Truto Link SDK for the browser\n\n> **Try it in the browser:** The [Truto Link SDK Playground](https://playground.truto.one/) lets you try Connect, File Picker, and RapidForm flows interactively—no setup required.\n\nThis package allows you to connect your customer's accounts to your Truto account and also show the RapidForm after an integrated account is connected.\n\nTo 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](https://truto.one/docs/api-reference/admin/link-token/create).\n\nTo 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](https://truto.one/docs/api-reference/admin/integrated-accounts/create-token).\n\n## Installation\n\n```bash\nnpm install @truto/truto-link-sdk\n# yarn add @truto/truto-link-sdk\n```\n\n## Usage\n\n### Open the Truto Connect UI\n\n```javascript\nimport authenticate from '@truto/truto-link-sdk';\n\nconst linkToken = 'link-token-uuid';\nconst options = {}; // refer Options section below\n\n// authenticate opens a new window with the Truto Link UI, and returns a promise\n// which resolves after your customer has successfully connected their account.\n// It rejects if the customer closes the window or if there was an error while connecting their account.\n\nauthenticate(linkToken, options)\n .then((response) => {\n console.log(response);\n // { result: 'success', integration: 'copper' }\n })\n .catch((error) => {\n console.log(error);\n });\n```\n\n### Open the RapidForm UI\n\n```javascript\nimport { rapidForm } from '@truto/truto-link-sdk';\n\nconst integratedAccountToken = 'integrated-account-token-uuid';\n\n// rapidForm opens a new window with the RapidForm for the integrated account, and returns a promise\n// which resolves after your customer has successfully selects the data they need.\n// It rejects if the customer closes the window or if there was an error while saving the selection.\n\nrapidForm(integratedAccountToken, {})\n .then((response) => {\n console.log(response);\n // { result: 'success', integration: 'copper' }\n })\n .catch((error) => {\n console.log(error);\n });\n```\n\n## Options\n\nThe `authenticate` method accepts the following options as the second argument.\n\n- `integration` - Optional. String. The name of the integration you want to pre-select. This will skip the integration selection screen.\n- `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.\n- `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.\n- `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.\n- `iframe` - Optional. Boolean. Default: true. Shows the connection UI inside an iframe.\n- `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.\n- `integrations` - Optional. Array of Strings. The integrations to show in the integration list and allow the customer to connect.\n- `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](https://truto.one/docs/api-reference/admin/link-token/create#request-body) 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.\n- `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,\n ```\n {\n \"field_name_1\": {\n \"message\": \"Reason for allowing deselection of values\"\n },\n \"field_name_2\": ...\n }\n ```\n- `disabledFields` - Optional. Object. Default: empty. Used in RapidForm. Allows you to disable fields in the RapidForm. Accepts value in the following format,\n ```\n {\n \"field_name_1\": {\n \"message\": \"Reason for disabling the field\"\n },\n \"field_name_2\": ...\n }\n ```\n- `baseUrl` - Optional. String. Default: `https://app.truto.one`. Accepted by both `authenticate` and `rapidForm`. The origin that serves the Truto UI, optionally with a path prefix (`https://self-hosted.example/truto`). Set it only if you are pointing the SDK at a self-hosted or staging deployment. It must be an absolute `http(s)` URL — anything else throws rather than quietly falling back to production — and a trailing slash, query string or fragment is normalised away. The SDK accepts the result message from this origin and no other, and only from the overlay or popup that call opened, so it must match the origin that actually serves the UI (a redirect, including `http` to `https`, changes it).\n- `width` - Optional. Number. Default: 700. Accepted by both `authenticate` and `rapidForm`. Width in pixels of the popup window. Applies only when `iframe` is `false`; the iframe overlay always fills the viewport.\n- `height` - Optional. Number. Default: 800. Accepted by both `authenticate` and `rapidForm`. Height in pixels of the popup window. Applies only when `iframe` is `false`; the iframe overlay always fills the viewport.\n\n## Errors\n\nSomething 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,\n\n```json\n{\n \"result\": \"error\",\n \"error\": \"string describing the error\",\n \"error_type\": \"invalid_token | invalid_integration | connection_error | post_install_error | validation_error\",\n \"integration\": \"integration name\",\n \"integrated_account_id\": \"integrated account id\"\n}\n```\n\n`integrated_account_id` will be sent only if the error is `post_install_error` or `validation_error`.\n\n## Error types\n\n- `invalid_token` - The link token is invalid or expired.\n- `invalid_integration` - The integration name is invalid, has typo or is not installed in the environment.\n- `connection_error` - There was an error while connecting the account. Usually happens when the OAuth flow fails.\n- `post_install_error` - Occurs after the integrated account is created and when the post install steps setup for the integration fail.\n- `validation_error` - Occurs after the integrated account is created and while running the validation requests setup for the integration fail.\n- `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 -\n - `RapidForm is not setup.` - When there is no RapidForm setup for the integration.\n - `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.\n - `There was an error fetching the resources for the fields in the RapidForm: