Types Reference

// Client options
interface CadraClientOptions {
  apiKey?: string;
  token?: string;
  tokenProvider?: () => Promise<string>;
  orgId: number;
  baseUrl?: string;
}

// Execution
interface ExecuteInput {
  task: string;
  context?: Record<string, unknown>;
  attachmentIds?: string[];
  teamUuid?: string;
}

interface ExecutionResult {
  executionId: string;
  sessionId: string;
}

interface Execution {
  id: string;
  status: 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
  output?: string;
  toolResults?: ToolCallResult[];
  sessionId: string;
  startedAt: string;
  completedAt?: string;
}

// Tool results
interface ToolCallResult {
  toolCallId: string;
  name: string;
  input: Record<string, unknown>;
  output: unknown;
  images?: Array<{ url: string }>;
}

// Streaming
interface StreamConfig {
  maxRetries?: number;
  retryDelay?: number;
  maxRetryDelay?: number;
  tokenProvider?: () => Promise<string>;
}

// Chat adapter interface
interface ChatAdapter {
  startExecution(input: StartExecutionInput): Promise<ExecutionResult>;
  sendMessage(input: SendMessageInput): Promise<ExecutionResult>;
  cancelExecution(uuid: string): Promise<void>;
  getExecution(uuid: string): Promise<Execution>;
  getUploadUrl(input: UploadUrlInput): Promise<UploadUrlResult>;
  confirmUpload(uuid: string): Promise<void>;
  getDownloadUrl(uuid: string): Promise<string>;
  getSessionHistory?(sessionId: string): Promise<SessionHistory>;
  getSessionArtifacts?(sessionId: string): Promise<Artifact[]>;
  createStream?(executionId: string, sessionId?: string): ExecutionStreamController;
}

// Chat messages
interface ChatMessage {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: string;
  toolCalls?: ToolCallResult[];
  attachments?: AttachmentRef[];
  isStreaming?: boolean;
}

// File attachments
interface AttachmentRef {
  uuid: string;
  filename: string;
  mimeType: string;
  sizeBytes: number;
  status: 'uploading' | 'ready' | 'error';
}

interface UploadUrlInput {
  filename: string;
  mimeType: string;
  sizeBytes: number;
}

interface UploadUrlResult {
  uuid: string;
  uploadUrl: string;
}

type StreamEvent =
  | { type: 'textDelta'; delta: string }
  | { type: 'toolCall'; name: string; input: unknown; toolCallId: string }
  | { type: 'toolResult'; toolCallId: string; output: unknown }
  | { type: 'started'; executionId: string }
  | { type: 'progress'; percent: number; message?: string }
  | { type: 'statusUpdate'; status: string; message?: string }
  | { type: 'log'; level: 'debug' | 'info' | 'warn' | 'error'; message: string }
  | { type: 'delegationStarted'; delegationId: string; agentName: string }
  | { type: 'delegationCompleted'; delegationId: string; result: unknown }
  | { type: 'executionPaused'; prompt: string; options?: string[] }
  | { type: 'complete'; execution: Execution }
  | { type: 'error'; error: CadraError };

class CadraError extends Error {
  code: string;
  status: number;
  message: string;
  requestId?: string;
}

class AuthenticationError extends CadraError {} // 401
class AuthorizationError extends CadraError {}  // 403
class NotFoundError extends CadraError {}       // 404
class ValidationError extends CadraError {      // 400/422
  errors: Array<{ field: string; message: string }>;
}
class ConflictError extends CadraError {}       // 409
class RateLimitError extends CadraError {       // 429
  retryAfter?: number;
}
class ServerError extends CadraError {}         // 5xx
class NetworkError extends CadraError {}        // 0