# TypeScript SDK

> Source: https://truto.one/docs/sdks/typescript/

`@truto/truto-ts-sdk` is a TypeScript/JavaScript library to interact with the Truto API, a powerful integration platform for connecting multiple SaaS applications. The SDK mirrors the Truto REST API endpoints, which are documented in the [Truto API Reference](/docs/api-reference/overview/introduction).

## Requirements

Node.js 18+ (the library uses `fetch`)

## Installation

```bash
npm install @truto/truto-ts-sdk
```

or via yarn:

```bash
yarn add @truto/truto-ts-sdk
```

## Usage

### ESM Import

```javascript
import TrutoApi from '@truto/truto-ts-sdk'
```

### CommonJS Import

```javascript
const { default: TrutoApi } = require('@truto/truto-ts-sdk');
```

### Initializing the client

```javascript
const trutoApi = new TrutoApi({
  token: process.env.TRUTO_API_TOKEN,
})
```

### Calling the APIs

```javascript
// Fetch all installed integrations
const installedIntegrations = await trutoApi.environmentIntegration.list()
for await (const installedIntegration of installedIntegrations) {
  console.log(installedIntegration)
}

// Fetch integrated accounts for a tenant
const integratedAccounts = await trutoApi.integratedAccount.list({
  tenant_id: 'acme-1',
})
console.log(await integratedAccount.toArray()) // To fetch all

// Install an integration to the environment the API token is associated with
await trutoApi.integration.install('32b122db-ad24-400f-8ee7-0be21edc12ef')

// Make a request to the unified API
const unifiedApiCursor = await trutoApi.unifiedApi.list({
  unified_model: 'accounting',
  resource: 'accounts',
  integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
  created_at: '2023-05-01T00:00:00.000Z',
})
for await (const unifiedApiResource of unifiedApiCursor) {
  console.log(unifiedApiResource)
}

const unifiedApiResource = await trutoApi.unifiedApi.get('1', {
  unified_model: 'accounting',
  resource: 'accounts',
  integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
})
console.log(unifiedApiResource)
```

## Available Tools

The SDK provides a way to discover available tools and their schemas for each integrated account. This is particularly useful when building LLM-powered applications:

```javascript
// Get available tools for an integrated account
const tools = await trutoApi.integratedAccount.tools(
  '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
  ['list', 'get']
)
console.log(tools)

// Get all tools without filtering by method
const allTools = await trutoApi.integratedAccount.tools(
  '766cc1ee-6637-4aa1-a73e-a0c89ccc867c'
)
```

Each tool in the response includes:

- `resource` — The resource name (e.g., `tickets`, `accounts`)
- `method` — The available method (e.g., `list`, `get`, `create`)
- `name` — A human-readable name for the tool
- `description` — A description of what the tool does
- `query_schema` — JSON schema for query parameters
- `body_schema` — JSON schema for request body (if applicable)
- `required` — Array of required parameter names

Truto provides a toolset for [Langchain.js](https://github.com/trutohq/truto-langchainjs-toolset) as well.

## Retry Options

The SDK provides built-in retry mechanisms to handle rate limits and transient failures:

```javascript
const result = await trutoApi.unifiedApi.list({
  unified_model: 'accounting',
  resource: 'accounts',
  integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
}, {
  noRetry: true,
  retryStatusCodes: [429, 503],
  defaultRetryAfter: 5,
  maxRetries: 5,
  timeout: 60,
  onRetry: (retryCount, statusCode) => {
    console.log(`Retry attempt ${retryCount} due to status code ${statusCode}`);
  },
  onRateLimited: (retryAfter, retryCount) => {
    console.log(`Rate limited, waiting ${retryAfter}s before retry ${retryCount + 1}`);
  }
});
```

| Option | Default | Description |
|--------|---------|-------------|
| `noRetry` | `false` | Disable retries for this request |
| `retryStatusCodes` | `[408, 409, 425, 429, 502, 503, 504]` | HTTP status codes to retry on |
| `defaultRetryAfter` | `10` | Retry delay in seconds |
| `maxRetries` | `3` | Maximum number of retries |
| `timeout` | `30` | Request timeout in seconds |
| `onRetry` | — | Callback notified on retries |
| `onRateLimited` | — | Callback notified on 429 responses |

## Request Queue

For high-volume API requests with rate limiting, the SDK provides a request queue:

```javascript
import TrutoApi, { RequestQueue } from '@truto/truto-ts-sdk'

const truto = new TrutoApi({
  token: process.env.TRUTO_API_TOKEN,
  baseUrl: process.env.TRUTO_API_BASE_URL,
})

const queue = new RequestQueue(truto, {
  concurrency: 5,
  interval: 1000,
})

const response = await queue.proxyApi
  .list({
    integrated_account_id: '820b732c-bd4d-4b98-b33e-fda752a368ff',
    resource: 'tickets',
    limit: 10,
  })
  .toArray()
```

## File Uploads

The SDK supports file uploads using `FormData`:

```javascript
const formData = new FormData();
formData.append('file', fileObject);
formData.append('name', 'example.pdf');

await trutoApi.unifiedApi.create(formData, {
  unified_model: 'file-storage',
  resource: 'drive-items',
  integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
});

// With body passthrough (sends FormData directly to integration)
await trutoApi.unifiedApi.create('documents', formData, {
  unified_model: 'file-storage',
  resource: 'drive-items',
  integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
  truto_body_passthrough: true,
});
```