> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chucky.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> JavaScript/TypeScript SDK type definitions

# Types

Complete type definitions for the JavaScript/TypeScript SDK.

## Client Types

### ClientOptions

```typescript theme={null}
interface ClientOptions {
  token: string;
  baseUrl?: string;
  debug?: boolean;
  timeout?: number;
  keepAliveInterval?: number;
}
```

### ConnectionStatus

```typescript theme={null}
type ConnectionStatus =
  | 'disconnected'
  | 'connecting'
  | 'connected'
  | 'error';
```

### ClientEventHandlers

```typescript theme={null}
interface ClientEventHandlers {
  onConnect?: () => void;
  onDisconnect?: (reason: string) => void;
  onError?: (error: Error) => void;
}
```

## Session Types

### SessionOptions

```typescript theme={null}
interface SessionOptions extends BaseOptions {
  sessionId?: string;
  forkSession?: string;
  resumeSessionAt?: string;
  continue?: boolean;
  settingSources?: SettingSource[];
}

type SettingSource = 'user' | 'project' | 'local';
```

### SessionState

```typescript theme={null}
type SessionState =
  | 'idle'
  | 'initializing'
  | 'ready'
  | 'processing'
  | 'waiting_tool'
  | 'completed'
  | 'error';
```

### SessionEventHandlers

```typescript theme={null}
interface SessionEventHandlers {
  onSessionInfo?: (info: SessionInfo) => void;
  onMessage?: (message: Message) => void;
  onText?: (text: string) => void;
  onToolUse?: (tool: ToolCall) => void;
  onToolResult?: (callId: string, result: ToolResult) => void;
  onThinking?: (thinking: string) => void;
  onComplete?: (result: SessionResult) => void;
  onError?: (error: Error) => void;
}
```

### SessionInfo

```typescript theme={null}
interface SessionInfo {
  sessionId: string;
  model: string;
  created: string;
}
```

## Options Types

### BaseOptions

Shared options for sessions and prompts.

```typescript theme={null}
interface BaseOptions {
  // Model
  model?: string;
  fallbackModel?: string;

  // System prompt
  systemPrompt?: string | SystemPromptConfig;

  // Tools
  tools?: ToolDefinition[];
  allowedTools?: string[];
  disallowedTools?: string[];
  mcpServers?: McpServer[];

  // Limits
  maxTurns?: number;
  maxBudgetUsd?: number;

  // Output
  outputFormat?: OutputFormat;

  // Advanced
  agents?: AgentConfig[];
  betas?: string[];
  permissionMode?: PermissionMode;
  allowDangerouslySkipPermissions?: boolean;
  env?: Record<string, string>;
  includePartialMessages?: boolean;
  maxThinkingTokens?: number;
}
```

### PromptOptions

```typescript theme={null}
interface PromptOptions extends BaseOptions {
  message: string;
}
```

### SystemPromptConfig

```typescript theme={null}
type SystemPromptConfig =
  | string
  | {
      type: 'preset';
      preset: 'claude_code';
      append?: string;
    };
```

### OutputFormat

```typescript theme={null}
interface OutputFormat {
  type: 'json_schema';
  schema: Record<string, unknown>;
}
```

### PermissionMode

```typescript theme={null}
type PermissionMode = 'default' | 'plan' | 'bypassPermissions';
```

## Result Types

### SessionResult

```typescript theme={null}
interface SessionResult {
  type: 'result';
  subtype?: 'success' | 'error' | 'interrupted';
  text?: string;
  messages?: Message[];
  total_cost_usd?: number;
  duration_secs?: number;
  turn_count?: number;
  usage?: Usage;
  session_id?: string;
  error?: string;
}
```

### PromptResult

```typescript theme={null}
interface PromptResult {
  type: 'result';
  subtype?: 'success' | 'error';
  text?: string;
  output?: unknown;
  total_cost_usd?: number;
  duration_secs?: number;
  usage?: Usage;
  error?: string;
}
```

### Usage

```typescript theme={null}
interface Usage {
  input_tokens: number;
  output_tokens: number;
  cache_creation_input_tokens?: number;
  cache_read_input_tokens?: number;
}
```

## Message Types

### Message

```typescript theme={null}
interface Message {
  role: 'user' | 'assistant' | 'system';
  content: ContentBlock[] | string;
}
```

### ContentBlock

```typescript theme={null}
type ContentBlock =
  | TextBlock
  | ImageBlock
  | DocumentBlock
  | ToolUseBlock
  | ToolResultBlock
  | ThinkingBlock;

interface TextBlock {
  type: 'text';
  text: string;
}

interface ImageBlock {
  type: 'image';
  source: {
    type: 'base64';
    media_type: string;  // e.g., 'image/png', 'image/jpeg'
    data: string;
  };
}

interface DocumentBlock {
  type: 'document';
  source: {
    type: 'base64';
    media_type: string;  // e.g., 'application/pdf'
    data: string;
  };
}

interface ToolUseBlock {
  type: 'tool_use';
  id: string;
  name: string;
  input: Record<string, unknown>;
}

interface ToolResultBlock {
  type: 'tool_result';
  tool_use_id: string;
  content: ContentBlock[] | string;
  is_error?: boolean;
}

interface ThinkingBlock {
  type: 'thinking';
  thinking: string;
}
```

## Streaming Types

### StreamingEvent

```typescript theme={null}
type StreamingEvent =
  | StreamingTextEvent
  | StreamingToolUseEvent
  | StreamingToolResultEvent
  | StreamingThinkingEvent
  | StreamingErrorEvent;

interface StreamingTextEvent {
  type: 'text';
  text: string;
}

interface StreamingToolUseEvent {
  type: 'tool_use';
  id: string;
  name: string;
  input: Record<string, unknown>;
}

interface StreamingToolResultEvent {
  type: 'tool_result';
  id: string;
  content: unknown;
  isError?: boolean;
}

interface StreamingThinkingEvent {
  type: 'thinking';
  thinking: string;
}

interface StreamingErrorEvent {
  type: 'error';
  error: Error;
}
```

## Tool Types

### ToolDefinition

```typescript theme={null}
interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: ToolInputSchema;
  executeIn?: 'server' | 'browser';
  handler?: ToolHandler;
}
```

### ToolInputSchema

```typescript theme={null}
interface ToolInputSchema {
  type: 'object';
  properties: Record<string, PropertySchema>;
  required?: string[];
}

interface PropertySchema {
  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
  description?: string;
  enum?: string[];
  items?: PropertySchema;
  properties?: Record<string, PropertySchema>;
  required?: string[];
  default?: unknown;
  minimum?: number;
  maximum?: number;
}
```

### ToolHandler

```typescript theme={null}
type ToolHandler = (
  input: Record<string, unknown>
) => Promise<ToolResult>;
```

### ToolResult

```typescript theme={null}
interface ToolResult {
  content: ToolContentBlock[];
  isError?: boolean;
}

type ToolContentBlock =
  | { type: 'text'; text: string }
  | { type: 'image'; data: string; mimeType: string };
```

### ToolCall

```typescript theme={null}
interface ToolCall {
  id: string;
  name: string;
  input: Record<string, unknown>;
}
```

## MCP Types

### McpServer

```typescript theme={null}
interface McpServer {
  name: string;
  version: string;
  tools: ToolDefinition[];
}
```

## Token Types

### CreateTokenOptions

```typescript theme={null}
interface CreateTokenOptions {
  userId: string;
  projectId: string;
  secret: string;
  expiresIn?: number;
  budget: TokenBudget;
  permissions?: TokenPermissions;
  sdkConfig?: TokenSdkConfig;
}
```

### TokenBudget

```typescript theme={null}
interface TokenBudget {
  ai: number;
  compute: number;
  window: 'hour' | 'day' | 'week' | 'month' | 'lifetime';
  windowStart: string;
}
```

### TokenPermissions

```typescript theme={null}
interface TokenPermissions {
  tools?: string[];
  blockedTools?: string[];
  maxTurns?: number;
  model?: string;
}
```

### TokenSdkConfig

```typescript theme={null}
interface TokenSdkConfig {
  model?: string;
  systemPrompt?: string;
  tools?: unknown;
  allowedTools?: string[];
  disallowedTools?: string[];
  maxTurns?: number;
  maxBudgetUsd?: number;
  maxThinkingTokens?: number;
  permissionMode?: string;
  allowDangerouslySkipPermissions?: boolean;
  mcpServers?: unknown[];
  agents?: unknown;
  betas?: string[];
  outputFormat?: string;
  env?: Record<string, string>;
}
```

### DecodedToken

```typescript theme={null}
interface DecodedToken {
  sub: string;
  iss: string;
  exp: number;
  iat?: number;
  budget: TokenBudget;
  permissions?: TokenPermissions;
  sdkConfig?: TokenSdkConfig;
}
```

## Error Types

### ChuckyError

```typescript theme={null}
class ChuckyError extends Error {
  readonly code: string;
  readonly details?: Record<string, unknown>;
}
```

### Error Codes

```typescript theme={null}
type ErrorCode =
  | 'CONNECTION_ERROR'
  | 'AUTHENTICATION_ERROR'
  | 'BUDGET_EXCEEDED'
  | 'CONCURRENCY_LIMIT'
  | 'RATE_LIMIT'
  | 'SESSION_ERROR'
  | 'TOOL_EXECUTION_ERROR'
  | 'TIMEOUT'
  | 'VALIDATION_ERROR';
```