DevTeamClient

The DevTeamClient class is the primary entry point for the SDK. It manages authentication, HTTP requests, WebSocket connections, and provides all orchestration methods.

Constructor

import { DevTeamClient } from 'devteam-sdk';
 
const client = new DevTeamClient(options?: DevTeamClientOptions);

Options

interface DevTeamClientOptions {
  /** Base URL of the DevTeam API. Default: DEVTEAM_API_URL env var */
  apiUrl?: string;
 
  /** API key for authentication. Default: DEVTEAM_API_KEY env var */
  apiKey?: string;
 
  /** JWT token (alternative to API key). */
  token?: string;
 
  /** Request timeout in milliseconds. Default: 30000 */
  timeout?: number;
 
  /** Maximum retry attempts for failed requests. Default: 3 */
  maxRetries?: number;
 
  /** Logging level. Default: 'info' */
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
 
  /** Default task queue. Default: 'default' */
  defaultQueue?: string;
 
  /** Default model for tasks. Default: 'sonnet' */
  defaultModel?: string;
 
  /** Custom HTTP headers sent with every request. */
  headers?: Record<string, string>;
 
  /** Model routing configuration. */
  modelConfig?: ModelConfig;
 
  /** WebSocket options for real-time subscriptions. */
  websocket?: {
    /** Enable WebSocket connection. Default: false */
    enabled?: boolean;
    /** Auto-reconnect on disconnect. Default: true */
    autoReconnect?: boolean;
    /** Reconnect interval in ms. Default: 5000 */
    reconnectInterval?: number;
  };
}

Authentication

The client supports three authentication methods:

API Key

const client = new DevTeamClient({
  apiUrl: 'https://devteam.marsala.dev',
  apiKey: 'dtk_live_abc123def456',
});

JWT Token

const client = new DevTeamClient({
  apiUrl: 'https://devteam.marsala.dev',
  token: 'eyJhbGciOiJIUzI1NiIs...',
});

Environment Variables

// Reads DEVTEAM_API_URL and DEVTEAM_API_KEY from env
const client = new DevTeamClient();

Connection Management

Health Check

const health = await client.healthCheck();
// {
//   status: 'healthy',
//   version: '1.0.0',
//   uptime: 86400,
//   temporal: 'connected',
//   database: 'connected',
//   workers: {
//     total: 5,
//     active: 3,
//     idle: 2,
//   },
// }

WebSocket Subscriptions

Subscribe to real-time events:

const client = new DevTeamClient({
  apiUrl: 'https://devteam.marsala.dev',
  apiKey: process.env.DEVTEAM_API_KEY,
  websocket: { enabled: true },
});
 
// Subscribe to all task events
client.subscribe('task:*', (event) => {
  console.log('Task event:', event.type, event.taskId, event.status);
});
 
// Subscribe to a specific task
client.subscribe('task:dt_task_abc123', (event) => {
  if (event.status === 'completed') {
    console.log('Task done:', event.output);
  }
});
 
// Subscribe to plan execution events
client.subscribe('plan:dt_exec_xyz789', (event) => {
  console.log(`Step ${event.stepId}: ${event.status}`);
});
 
// Subscribe to HITL approval requests
client.subscribe('hitl:pending', (event) => {
  console.log('Approval needed:', event.taskId, event.summary);
});
 
// Unsubscribe
const unsubscribe = client.subscribe('task:*', handler);
unsubscribe();

Disconnect

// Gracefully close all connections
await client.disconnect();

Request Configuration

Retry Behavior

Failed requests are retried with exponential backoff:

Attempt 1: immediate
Attempt 2: 1 second delay
Attempt 3: 2 seconds delay
Attempt 4: 4 seconds delay (if maxRetries >= 4)

Retries are triggered for:

HTTP 429 (Too Many Requests)
HTTP 500, 502, 503, 504 (Server errors)
Network timeouts
Connection refused

⚠️

Retries are NOT triggered for 400 (Bad Request) or 401/403 (Auth errors). These indicate client-side issues that retrying will not fix.

Custom Headers

const client = new DevTeamClient({
  headers: {
    'X-Request-Source': 'ci-pipeline',
    'X-Correlation-Id': 'build-12345',
  },
});

Logging

The client includes structured logging:

const client = new DevTeamClient({ logLevel: 'debug' });
 
// Logs output:
// [DevTeam] DEBUG: POST /api/tasks { model: 'sonnet', queue: 'default' }
// [DevTeam] DEBUG: Response 201 in 342ms { taskId: 'dt_task_abc123' }
// [DevTeam] INFO:  Task dt_task_abc123 created successfully

Custom logger:

const client = new DevTeamClient({
  logger: {
    debug: (msg, data) => myLogger.debug(msg, data),
    info: (msg, data) => myLogger.info(msg, data),
    warn: (msg, data) => myLogger.warn(msg, data),
    error: (msg, data) => myLogger.error(msg, data),
  },
});

Next Steps

Tasks -- Create and manage tasks
Plans -- Build DAG workflows

Overview Tasks