TypeScript SDK | Truto Documentation

@truto/truto-ts-sdk is a TypeScript/JavaScript library to interact with the Truto API. The SDK mirrors the Unified, Proxy, Custom, and core Admin API endpoints of the Truto REST API, which are documented in the Truto API Reference. It does not wrap every endpoint; call the REST API directly for anything it does not expose.

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 = trutoApi.environmentIntegration.list()
for await (const installedIntegration of installedIntegrations) {
  console.log(installedIntegration)
}
 
// Fetch integrated accounts for a tenant
const integratedAccounts = trutoApi.integratedAccount.list({
  tenant_id: 'acme-1',
})
console.log(await integratedAccounts.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 = 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',
}, {
  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}`);
  }
}).toArray();

Option	Default	Description
`noRetry`	`false`	Disable retries for this request. When `true`, the other retry options have no effect
`retryStatusCodes`	`[408, 409, 425, 429, 502, 503, 504]`	Extra HTTP status codes to retry on. They are added to the defaults, so the defaults are always retried
`defaultRetryAfter`	`10`	Seconds to wait before retrying a `429` response that has no `Retry-After` header. Other retryable status codes are retried immediately
`maxRetries`	`3`	Maximum number of retries
`timeout`	`30`	Timeout in seconds for each attempt. A timed-out attempt throws an error with status code `408` and is not retried
`onRetry`	—	Callback notified on retries
`onRateLimited`	—	Callback notified on 429 responses

Numeric options set to 0 fall back to their defaults.

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(formData, {
  unified_model: 'file-storage',
  resource: 'drive-items',
  integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c',
  truto_body_passthrough: true,
});