> ## 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.
# III Client
> Initialize and configure the III SDK client
## init()
Initialize a new III SDK instance and connect to the engine.
```typescript theme={null}
import { init } from 'iii-sdk'
const iii = init(address, options?)
```
WebSocket URL of the III Engine (e.g., `ws://localhost:49199`)
Optional configuration for the SDK instance
Custom worker name for identification. Defaults to `hostname:pid`
Enable automatic worker metrics reporting via OpenTelemetry
Default timeout for function invocations in milliseconds (2 minutes)
WebSocket reconnection behavior configuration
Initial delay before first reconnection attempt
Maximum delay between reconnection attempts
Exponential backoff multiplier for reconnection delays
Random jitter factor (0-1) to prevent thundering herd
Maximum retry attempts (-1 for infinite)
OpenTelemetry configuration. OTel is enabled by default.
Enable OpenTelemetry. Set to `false` or env `OTEL_ENABLED=false` to disable
Service name for telemetry (also reads `OTEL_SERVICE_NAME` env var)
Service version (also reads `SERVICE_VERSION` env var)
Enable metrics export (also reads `OTEL_METRICS_ENABLED` env var)
Metrics export interval in milliseconds
Auto-instrument `fetch()` calls for HTTP client tracing
Custom OpenTelemetry instrumentations (e.g., PrismaInstrumentation)
Additional telemetry metadata
Language/locale for telemetry
Project name for telemetry grouping
Framework name (e.g., "express", "fastify")
An initialized III SDK instance
### Example
```typescript theme={null}
import { init } from 'iii-sdk'
const iii = init('ws://localhost:49199', {
workerName: 'api-worker-1',
invocationTimeoutMs: 30000, // 30 seconds
reconnectionConfig: {
maxRetries: 10,
initialDelayMs: 500
},
otel: {
serviceName: 'my-api-service',
serviceVersion: '1.0.0',
metricsEnabled: true
}
})
```
## Connection Management
### getConnectionState()
Get the current connection state.
```typescript theme={null}
const state = iii.getConnectionState()
```
Current connection state: `'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'`
### onConnectionStateChange()
Register a callback to be notified of connection state changes.
```typescript theme={null}
const unsubscribe = iii.onConnectionStateChange((state) => {
console.log('Connection state:', state)
})
// Later: unsubscribe
unsubscribe()
```
Function called when connection state changes
Function to unregister the callback
### Example: Connection State Handling
```typescript theme={null}
import { init } from 'iii-sdk'
const iii = init('ws://localhost:49199')
iii.onConnectionStateChange((state) => {
switch (state) {
case 'connected':
console.log('✓ Connected to III Engine')
break
case 'reconnecting':
console.warn('⟳ Reconnecting...')
break
case 'failed':
console.error('✗ Connection failed')
break
}
})
```
## Lifecycle Management
### shutdown()
Gracefully shutdown the SDK, cleaning up all resources.
```typescript theme={null}
await iii.shutdown()
```
This method:
* Stops all metrics reporting
* Flushes and shuts down OpenTelemetry
* Rejects all pending invocations
* Closes the WebSocket connection
* Clears all callbacks
### Example: Graceful Shutdown
```typescript theme={null}
import { init } from 'iii-sdk'
const iii = init('ws://localhost:49199')
// Handle shutdown signals
process.on('SIGINT', async () => {
console.log('Shutting down...')
await iii.shutdown()
process.exit(0)
})
process.on('SIGTERM', async () => {
console.log('Shutting down...')
await iii.shutdown()
process.exit(0)
})
```
## Engine Queries
### listFunctions()
List all functions registered across the III network.
```typescript theme={null}
const functions = await iii.listFunctions()
```
Array of registered function information
Function ID/path
Function description
Input schema definition
Output schema definition
Custom function metadata
### listWorkers()
List all workers connected to the engine.
```typescript theme={null}
const workers = await iii.listWorkers()
```
Array of connected worker information
Worker unique ID
Worker name
Runtime identifier (e.g., "node")
SDK version
Worker status: `'connected' | 'available' | 'busy' | 'disconnected'`
Number of functions registered by this worker
Number of currently executing invocations
### Example: Service Discovery
```typescript theme={null}
// Discover available functions
const functions = await iii.listFunctions()
console.log('Available functions:')
for (const fn of functions) {
console.log(`- ${fn.function_id}: ${fn.description || 'No description'}`)
}
// Monitor worker health
const workers = await iii.listWorkers()
console.log(`\n${workers.length} workers online`)
for (const worker of workers) {
console.log(`- ${worker.name}: ${worker.function_count} functions, ${worker.active_invocations} active`)
}
```