Documentation Index
Fetch the complete documentation index at: https://mintlify.com/iii-hq/sdk/llms.txt
Use this file to discover all available pages before exploring further.
Initialize the SDK
Connect to the III Engine by initializing the SDK with your engine’s WebSocket URL:
import { init } from 'iii-sdk'
const iii = init('ws://localhost:49199')
- Establishes a WebSocket connection to the engine
- Initializes OpenTelemetry for distributed tracing
- Sets up automatic reconnection on connection loss
Register a Function
Functions are the building blocks of III applications. Register a function to make it callable by other services:
const echoFunction = iii.registerFunction(
{ id: 'my_service::echo' },
async (data: { message: string }) => {
return { echoed: data.message }
}
)
Use :: to namespace your functions (e.g., service::function_name). This helps organize functions by service.
Call a Function
Call any registered function across the III network:
const result = await iii.call<{ message: string }, { echoed: string }>(
'my_service::echo',
{ message: 'Hello, III!' }
)
console.log(result.echoed) // "Hello, III!"
Access Context
Every function handler has access to a context with a logger and trace span:
import { getContext } from 'iii-sdk'
iii.registerFunction(
{ id: 'my_service::process' },
async (data: { items: string[] }) => {
const { logger, trace } = getContext()
logger.info('Processing items', { count: data.items.length })
// Add custom trace attributes
trace?.setAttribute('item.count', data.items.length)
return { processed: data.items.length }
}
)
Register an HTTP Trigger
Expose functions as HTTP endpoints:
// Register the function
const apiFunction = iii.registerFunction(
{ id: 'api::get_user' },
async (req: HttpRequest): Promise<ApiResponse> => {
const userId = req.path_params.id
return {
status_code: 200,
body: { id: userId, name: 'John Doe' }
}
}
)
// Register the HTTP trigger
const trigger = iii.registerTrigger({
type: 'http',
function_id: 'api::get_user',
config: {
api_path: 'users/:id',
http_method: 'GET'
}
})
http://localhost:3199/users/:id (default engine HTTP port).
Complete Example
Here’s a complete application that registers a function and an HTTP endpoint:
import { init, getContext, type HttpRequest, type ApiResponse } from 'iii-sdk'
const iii = init('ws://localhost:49199')
// Business logic function
iii.registerFunction(
{
id: 'tasks::create',
description: 'Create a new task'
},
async (data: { title: string; description: string }) => {
const { logger } = getContext()
logger.info('Creating task', { title: data.title })
const task = {
id: crypto.randomUUID(),
title: data.title,
description: data.description,
created_at: new Date().toISOString()
}
return task
}
)
// HTTP endpoint
iii.registerFunction(
{ id: 'api::create_task' },
async (req: HttpRequest): Promise<ApiResponse> => {
const body = req.body as { title: string; description: string }
// Call the business logic function
const task = await iii.call('tasks::create', body)
return {
status_code: 201,
body: task
}
}
)
iii.registerTrigger({
type: 'http',
function_id: 'api::create_task',
config: {
api_path: 'tasks',
http_method: 'POST'
}
})
console.log('Service started! Available endpoints:')
console.log('POST http://localhost:3199/tasks')
Next Steps
Functions
Learn about function handlers and registration
Triggers
Explore trigger types and HTTP endpoints
Context
Use context for logging and tracing
Channels
Stream data between functions