Creating a Client

createClient is the main entry point. It returns a fully-typed client object that covers every Terrantula API resource.

Signature

import { createClient } from '@terrantula/sdk'
import type { CreateClientOptions, TokenSource } from '@terrantula/sdk'

// Static token string
const client = createClient('https://terrantula.example.com', 'terr_xxxxxxxxxxxx')

// Options object
const client2 = createClient('https://terrantula.example.com', {
  token: 'terr_xxxxxxxxxxxx',
})

TokenSource

TokenSource is string | (() => string | Promise<string>). Pass a factory when the token rotates (e.g. fetched from a secrets manager at call time):

import { createClient } from '@terrantula/sdk'

const client = createClient('https://terrantula.example.com', {
  token: async () => {
    // Fetch a fresh token from your secrets manager on each request
    return 'terr_fresh_token'
  },
})

CreateClientOptions

Property	Type	Description
`token`	`TokenSource \| undefined`	API token or token factory. Omit for unauthenticated requests.
`fetch`	`typeof globalThis.fetch \| undefined`	Override the fetch implementation. Useful in tests — pass your Hono app's `.fetch`.

Project-scoped and env-scoped access

Resources are organized at three scopes. Every method takes a single params object:

Cloud scope — org and project management, GitHub integration:

import { createClient } from '@terrantula/sdk'

const client = createClient('https://terrantula.example.com', 'terr_xxxxxxxxxxxx')

// Create a project
const project = await client.projects.create({
  orgId: 'my-org',
  name: 'infra',
  slug: 'infra',
})

Project scope — entity types, cells, actions, audit log, stats:

import { createClient } from '@terrantula/sdk'

const client = createClient('https://terrantula.example.com', 'terr_xxxxxxxxxxxx')

// Project-scoped: entity types catalog
const entityTypes = await client.entityTypes.list({
  orgId: 'my-org',
  projectId: 'infra',
})
const cells = await client.cells.list({
  orgId: 'my-org',
  projectId: 'infra',
})

Env scope — entities, relationships, secrets (environment-isolated):

import { createClient } from '@terrantula/sdk'

const client = createClient('https://terrantula.example.com', 'terr_xxxxxxxxxxxx')

// Env-scoped: entities in the production environment
const entities = await client.entities.list({
  orgId: 'my-org',
  projectId: 'infra',
  envName: 'production',
})

Test usage

Pass a Hono app's .fetch to run against the real API handler in tests without starting a server:

import { createClient } from '@terrantula/sdk'

// In a test, pass app.fetch directly:
declare const app: { fetch: typeof globalThis.fetch }

const client = createClient('http://localhost', {
  token: 'test-token',
  fetch: app.fetch,
})

ON THIS PAGE

#Creating a Client

#Signature

#TokenSource

#CreateClientOptions