---
title: Types & Constants
description: 'TypeScript types, interfaces, JobStatus, JOB_TYPES registry, and SDK constants'
full: true
---

This page catalogs the TypeScript types and constants the SDK exports — the shapes of its configuration, job progress events, submission parameters, and the `JOB_TYPES` registry of supported tools. Reach for it when you want compile-time safety on the values you pass to and receive from the [Client](/docs/api/sdk-client) and [Jobs](/docs/api/sdk-jobs) methods, or when you need the canonical list of valid tool names and job statuses. It also documents the Harness session types used by the [Harness Sessions API](/docs/api/sessions-overview).

## SDK Types Reference

> **Planned specification.** `@ivybiosciences/sdk` is not released, and there is no package to install. This page describes the SDK's planned interface. To call the platform today, use the [REST API](/docs/api/rest-jobs), the [ivybloom CLI](/docs/cli), or the [MCP server](/docs/cli/mcp).

Core TypeScript types exported from `@ivybiosciences/sdk`. These types define the SDK's configuration, events, and domain models.

```ts
import type {
  IvyClientConfig,
  JobStatus,
  JobProgress,
  JobProgressCallback,
  SubmitJobParams,
  SubmitAndWaitOptions,
  WebSocketOptions,
  JobType,
} from "@ivybiosciences/sdk"
```

---

## `JobStatus`

All possible states for a computational job in the IvyAI system.

```ts
type JobStatus =
  | "PENDING"
  | "STARTED"
  | "PROCESSING"
  | "PROGRESS"
  | "COMPLETED"
  | "FAILURE"
  | "CANCELLED"
  | "IMPORTED"
```

### Lifecycle Diagram

 STARTED
    STARTED --> PROCESSING
    PROCESSING --> COMPLETED
    PROCESSING --> FAILURE
    PROCESSING --> CANCELLED
    PROCESSING --> PROGRESS : repeated`}
  caption="Job status lifecycle."
/>

### Values

| Status | Description |
|--------|-------------|
| `PENDING` | Job accepted and queued for execution |
| `STARTED` | Modal container provisioned, initializing |
| `PROCESSING` | Main computation running |
| `PROGRESS` | Intermediate update (may include phase info) |
| `COMPLETED` | Finished successfully; results available |
| `FAILURE` | Fatal error; see `JobProgress.error` |
| `CANCELLED` | Cancelled by user before completion |
| `IMPORTED` | Migrated from another system (guest → authenticated) |

---

## `TERMINAL_STATUSES`

Set of `JobStatus` values that indicate a job has reached a final state.

```ts
const TERMINAL_STATUSES: ReadonlySet<JobStatus>
// Contains: "COMPLETED", "FAILURE", "CANCELLED"
```

Once a job is in a terminal status, it will never change status again.

### Example

```ts
import { TERMINAL_STATUSES } from "@ivybiosciences/sdk"

if (TERMINAL_STATUSES.has(job.status)) {
  console.log("Job is done")
}
```

---

## `IvyClientConfig`

Configuration for creating an `IvyClient` instance. Exactly one of `apiKey` or `getToken` must be provided.

```ts
interface IvyClientConfig {
  baseUrl?: string
  apiKey?: string
  getToken?: () => Promise<string | null>
  timeout?: number
  retries?: number
  onError?: (error: Error) => void
}
```

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `baseUrl` | `string` | Production endpoint | API base URL including `/api/v1` prefix |
| `apiKey` | `string` | — | API key with `ivy_` prefix. Mutually exclusive with `getToken` |
| `getToken` | `() => Promise<string \| null>` | — | Async JWT provider (e.g., Clerk). Mutually exclusive with `apiKey` |
| `timeout` | `number` | `30000` | HTTP request timeout in milliseconds |
| `retries` | `number` | `3` | Max retries for transient failures (429, 5xx) |
| `onError` | `(error: Error) => void` | — | Global callback for unhandled SDK errors |

### Examples

```ts
// Server-side with API key
const config: IvyClientConfig = {
  apiKey: "ivy_your_key_here",
  timeout: 60_000,
}

// Browser with Clerk JWT
const config: IvyClientConfig = {
  getToken: () => clerk.session!.getToken({ template: "ivy_api" }),
  baseUrl: "https://your-domain.com/api/v1",
}
```

---

## `JobProgress`

Real-time progress snapshot of a computational job. Delivered via WebSocket subscription or HTTP polling.

```ts
interface JobProgress {
  jobId: string
  status: JobStatus
  progress?: number
  phase?: string
  result?: Record<string, unknown>
  error?: string
  presignedUrl?: string
  updatedAt?: string
}
```

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `jobId` | `string` | Unique job identifier (format: `job_{uuid4}`) |
| `status` | `JobStatus` | Current lifecycle state |
| `progress` | `number?` | Overall completion percentage (0–100) |
| `phase` | `string?` | Current computational phase name |
| `result` | `Record<string, unknown>?` | Structured result data (only when COMPLETED) |
| `error` | `string?` | Error description (only when FAILURE) |
| `presignedUrl` | `string?` | Time-limited S3 download URL for artifacts |
| `updatedAt` | `string?` | ISO 8601 timestamp of last status change |

### Standard Phases

| Phase | Typical Progress | Description |
|-------|:---:|-------------|
| `initialization` | ~5% | Input validation |
| `data_preprocessing` | ~15% | Data loading and prep |
| `model_loading` | ~10% | ML model initialization |
| `main_computation` | ~50% | Core processing |
| `post_processing` | ~15% | Result analysis |
| `result_generation` | ~5% | Format and store |

### Examples

```ts
// During computation
{
  jobId: "job_abc123",
  status: "PROCESSING",
  progress: 45,
  phase: "main_computation"
}

// Completed result
{
  jobId: "job_abc123",
  status: "COMPLETED",
  progress: 100,
  result: { plddt_mean: 0.87, num_residues: 342 },
  presignedUrl: "https://<bucket>.s3.<region>.amazonaws.com/.../predicted_structure.pdb"
}
```

---

## `JobProgressCallback`

Callback function invoked with progress updates during job execution.

```ts
type JobProgressCallback = (progress: JobProgress) => void
```

Used by `SubmitAndWaitOptions.onProgress` and the `useIvyJob` hook.

---

## `SubmitJobParams`

Parameters for submitting a new computational job.

```ts
interface SubmitJobParams {
  toolName: string
  parameters: Record<string, unknown>
  projectId?: string
  jobTitle?: string
  orgId?: string
  analysisLevel?: "basic" | "standard" | "comprehensive"
}
```

### Fields

| Field | Type | Required | Description |
|-------|------|:---:|-------------|
| `toolName` | `string` | Yes | Computational tool to run (see `JOB_TYPES`) |
| `parameters` | `Record<string, unknown>` | Yes | Tool-specific input parameters |
| `projectId` | `string` | No | Project for billing/access control |
| `jobTitle` | `string` | No | Human-readable title for dashboard |
| `orgId` | `string` | No | Organization ID for team-scoped jobs |
| `analysisLevel` | `"basic" \| "standard" \| "comprehensive"` | No | Analysis depth (default: `"standard"`) |

### Analysis Levels

| Level | Description | Data Fields |
|-------|-------------|-------------|
| `basic` | Fast results, minimal metrics | Standard output only |
| `standard` | Balanced analysis (default) | Key quality metrics |
| `comprehensive` | Full analytical suite | 5-10x more fields |

### Examples

```ts
// ESMFold protein structure prediction
const params: SubmitJobParams = {
  toolName: "esmfold",
  parameters: { protein_sequence: "MKFLILLFNILCLFPVLAADNH" },
  analysisLevel: "comprehensive",
}

// DiffDock molecular docking
const params: SubmitJobParams = {
  toolName: "diffdock",
  parameters: {
    protein_pdb: "...",
    ligand_smiles: "CC(=O)Oc1ccccc1C(=O)O",
    num_poses: 10,
  },
  projectId: "proj_abc123",
  jobTitle: "Aspirin docking study",
}
```

---

## `SubmitAndWaitOptions`

Options for the `submitAndWait()` convenience method. Controls how the SDK monitors job progress until completion.

```ts
interface SubmitAndWaitOptions {
  onProgress?: JobProgressCallback
  pollInterval?: number
  timeout?: number
  useWebSocket?: boolean
}
```

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `onProgress` | `JobProgressCallback` | — | Called on each status/progress change |
| `pollInterval` | `number` | `3000` | Polling interval in ms (fallback mode) |
| `timeout` | `number` | `600000` | Max wait time in ms (throws `IvyTimeoutError`) |
| `useWebSocket` | `boolean` | `true` | Use WebSocket for real-time updates |

---

## `WebSocketOptions`

Configuration for WebSocket connection behavior. Controls reconnection strategy and lifecycle callbacks.

```ts
interface WebSocketOptions {
  autoReconnect?: boolean
  maxReconnectAttempts?: number
  reconnectInterval?: number
  onReconnect?: (attempt: number) => void
  onClose?: (code: number, reason: string) => void
}
```

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `autoReconnect` | `boolean` | `true` | Reconnect on unexpected close (non-1000 code) |
| `maxReconnectAttempts` | `number` | `5` | Max consecutive reconnection attempts |
| `reconnectInterval` | `number` | `1000` | Base delay in ms (doubles each attempt) |
| `onReconnect` | `(attempt: number) => void` | — | Called on each reconnection attempt |
| `onClose` | `(code: number, reason: string) => void` | — | Called when connection closes |

### Reconnection Backoff

```
Attempt 1: wait reconnectInterval ms         (1s)
Attempt 2: wait reconnectInterval * 2 ms     (2s)
Attempt 3: wait reconnectInterval * 4 ms     (4s)
Attempt 4: wait reconnectInterval * 8 ms     (8s)
Attempt 5: wait reconnectInterval * 16 ms    (16s)
— Give up after maxReconnectAttempts —
```

---

## `JobType`

Union type of all valid tool names. Derived from the `JOB_TYPES` constant.

```ts
type JobType = keyof typeof JOB_TYPES
// "esmfold" | "esm3_generate" | "diffdock" | "admet_ai" | ...
```

### Example

```ts
import type { JobType } from "@ivybiosciences/sdk"

const tool: JobType = "esmfold" // OK
const bad: JobType = "invalid"  // TypeScript error
```

---

## Constants

Exported constants from the main entry point:

```ts
import { DEFAULT_BASE_URL, JOB_TYPES } from "@ivybiosciences/sdk"
```

| Constant | Value | Description |
|----------|-------|-------------|
| `DEFAULT_BASE_URL` | `"https://www.ivybiosciences.com/api/v1"` | Planned default: the web app's API on our own domain |
| `JOB_TYPES` | `{ esmfold: "...", ... }` | Complete tool registry (see below) |

### Internal Defaults

These values are used internally by the SDK and configured via `IvyClientConfig` or `SubmitAndWaitOptions`. They are **not** exported but documented here for reference:

| Default | Value | Configured via |
|---------|-------|----------------|
| HTTP timeout | `30000` (30s) | `IvyClientConfig.timeout` |
| Retry attempts | `3` | `IvyClientConfig.retries` |
| Poll interval | `3000` (3s) | `SubmitAndWaitOptions.pollInterval` |
| Wait timeout | `600000` (10min) | `SubmitAndWaitOptions.timeout` |
| WS ping interval | `25000` (25s) | Not configurable |

---

## `JOB_TYPES` Registry

Complete registry of supported computational tools.

### Structure Prediction

| Key | Description |
|-----|-------------|
| `esmfold` | Protein structure prediction (GPU) |
| `esm3_generate` | ESM3 protein generation |
| `esm3_inverse_fold` | ESM3 inverse folding |
| `esm3_embeddings` | ESM3 protein embeddings |

### Molecular Docking & Design

| Key | Description |
|-----|-------------|
| `diffdock` | Protein-ligand docking (GPU) |
| `reinvent` | De novo molecule generation |
| `fragment_growing` | Fragment-based drug design. Retired, no replacement |
| `fragment_library` | Fragment library management. Retired, no replacement |

### Property Prediction

| Key | Description |
|-----|-------------|
| `admet_ai` | ADMET property prediction |
| `admetlab3` | ADMETLab3 comprehensive profiling. Retired, use `admet_ai` |
| `graphsol` | Aqueous solubility prediction |
| `deepsol` | Deep learning solubility. Not currently callable, use `graphsol` |
| `protox3` | Protein toxicity prediction. Retired, use `admet_ai` for the overlapping endpoints |
| `deeppurpose` | Drug-target interaction |

### Database Screening

| Key | Description |
|-----|-------------|
| `rdkit_full` | RDKit SMILES validation & properties |
| `zinc` | ZINC database screening |
| `pubchem` | PubChem compound queries |

### Sequence & Structure

| Key | Description |
|-----|-------------|
| `blast` | Sequence homology search |
| `biotite_fetch` | UniProt/PDB structure fetching |
| `aizynthfinder` | Retrosynthetic route planning |

### Literature & NLP

| Key | Description |
|-----|-------------|
| `biobert_pubmed` | Scientific literature mining |

### Example

```ts
import { JOB_TYPES } from "@ivybiosciences/sdk"

if ("esmfold" in JOB_TYPES) {
  console.log(JOB_TYPES.esmfold) // "Protein structure prediction (GPU)"
}
```

---

## Harness Types

Types used by the [Harness Sessions API](/docs/api/sessions-overview). Exported from `@pleach/core/types`.

### `SessionState`

The full state of a harness session.

```ts
interface SessionState {
  id: string
  userId: string
  title: string
  messages: SessionMessage[]
  toolCalls: ToolCallRecord[]
  artifacts: ArtifactRecord[]
  versionVector: VersionVector
  status: "active" | "archived"
  authPreset: "lenient" | "standard" | "light"
  createdAt: string
  updatedAt: string
}
```

### `StreamEvent`

Events emitted during harness session execution via SSE. See [Message Execution](/docs/api/sessions-execute#streamevent-types) for the full reference.

```ts
interface StreamEvent {
  type: StreamEventType
  data: Record<string, unknown>
}

type StreamEventType =
  | "message.start" | "message.delta" | "message.complete" | "message.citations" | "message.file"
  | "tool_call.start" | "tool_call.delta" | "tool_call.complete" | "tool_call.error" | "tool_call.pending"
  | "job.submitted" | "job.progress" | "job.completed" | "job.failed" | "job.cancelled"
  | "artifact.created" | "artifact.ready"
  | "interrupt.requested" | "interrupt.resolved"
  | "state.checkpoint" | "state.updated" | "state.rollback"
  | "sync.completed" | "sync.conflict"
  | "error.runtime" | "error.validation" | "error.tool"
```

### `VersionVector`

Used for multi-client synchronization. See [Sync Protocol](/docs/api/sessions-sync).

```ts
interface VersionVector {
  [clientId: string]: HybridTimestamp
}

interface HybridTimestamp {
  wallTime: number
  logical: number
  nodeId: string
}
```

### `SyncMode`

Conflict resolution mode for the sync endpoint.

```ts
type SyncMode = "merge" | "force_local" | "force_remote"
```

### `CheckpointSource`

What triggered a checkpoint.

```ts
type CheckpointSource = "message" | "tool_execution" | "job_complete" | "sync" | "manual"
```