TypeScript SDK | Truto Documentation

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

Requirements

Node.js 18+ (the library uses fetch)

Installation

npm install @truto/truto-ts-sdk

or via yarn:

yarn add @truto/truto-ts-sdk

Usage

ESM Import

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

CommonJS Import

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

Initializing the client

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

Calling the APIs

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

// 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 as well.

Retry Options

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

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:

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:

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