SDK Overview

The devteam-sdk package provides a typed TypeScript client for interacting with the DevTeam Orchestrator API. It handles authentication, request retries, WebSocket subscriptions, and type-safe response parsing.

Installation

npm install devteam-sdk

Basic Usage

import { DevTeamClient } from 'devteam-sdk';
 
const client = new DevTeamClient({
  apiUrl: 'https://devteam.marsala.dev',
  apiKey: process.env.DEVTEAM_API_KEY,
});

Module Structure

devteam-sdk
├── DevTeamClient          # Main client class
├── types/                 # TypeScript type definitions
│   ├── Task               # Task types
│   ├── Plan               # Plan/DAG types
│   ├── Template           # Template types
│   ├── HITL               # Human-in-the-Loop types
│   ├── WebSocket          # WebSocket event types
│   └── Error              # Error types
├── errors/                # Custom error classes
│   ├── DevTeamError       # Base error
│   ├── AuthError          # Authentication failures
│   ├── TimeoutError       # Request/task timeouts
│   └── ValidationError    # Input validation errors
└── utils/                 # Internal utilities
    ├── retry              # Retry logic
    ├── websocket          # WebSocket manager
    └── logger             # Structured logging

Core Capabilities

Tasks Plans & DAGs Fan-Out Human-in-the-Loop Templates Type Reference

Client Methods Summary

Method	Description	Section
`createTask()`	Submit a single task	Tasks
`getTaskStatus()`	Check task progress	Tasks
`waitForTask()`	Block until task completes	Tasks
`cancelTask()`	Cancel a running task	Tasks
`createPlan()`	Define a DAG workflow	Plans
`executePlan()`	Run a DAG plan	Plans
`getPlanStatus()`	Check plan execution progress	Plans
`waitForPlan()`	Block until plan completes	Plans
`executeFanOut()`	Run tasks in parallel	Fan-Out
`approveTask()`	Approve a HITL task	HITL
`rejectTask()`	Reject a HITL task	HITL
`getPendingApprovals()`	List tasks awaiting approval	HITL
`deployTemplate()`	Deploy a workflow template	Templates
`listTemplates()`	Browse available templates	Templates
`subscribe()`	WebSocket event subscription	Client

Error Handling

All SDK methods throw typed errors:

import { DevTeamError, AuthError, TimeoutError } from 'devteam-sdk';
 
try {
  const task = await client.createTask({ prompt: '...' });
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out after', error.timeoutMs, 'ms');
  } else if (error instanceof DevTeamError) {
    console.error('API error:', error.code, error.message);
  }
}

All errors include a requestId field that can be used for debugging with the DevTeam support team.

Next Steps

Client Reference -- Constructor options, authentication, and connection management
Tasks -- Working with individual tasks

First Workflow Client