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

# TypeScript Installation

> Install and set up the MutagenT TypeScript SDK

# TypeScript SDK Installation

## Install Package

<CodeGroup>
  ```bash bun (recommended) theme={null}
  bun add @mutagent/sdk
  ```

  ```bash npm theme={null}
  npm install @mutagent/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @mutagent/sdk
  ```
</CodeGroup>

<Note>
  The SDK (`v0.2.137`) ships as dual ESM + CJS. Both `import` and `require` work out of the box.
</Note>

## Requirements

| Requirement | Minimum |
| ----------- | ------- |
| TypeScript  | 5.0+    |
| Node.js     | 18+     |
| Bun         | 1.1+    |

## TypeScript Configuration

The SDK requires TypeScript 5.0+ for full type support.

```json theme={null}
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true
  }
}
```

## Initialize Client

The SDK auto-reads the `MUTAGENT_API_KEY` environment variable if no explicit credentials are provided.

```typescript theme={null}
import { Mutagent } from '@mutagent/sdk';

// Option 1: Auto-read from MUTAGENT_API_KEY env var (recommended)
const client = new Mutagent();

// Option 2: Explicit API key
const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY },
});

// Option 3: Bearer auth (OAuth flows)
const client = new Mutagent({
  security: { bearerAuth: 'your-oauth-token' },
});
```

## Verify Setup

```typescript theme={null}
// Test your connection
const prompts = await client.prompt.listPrompts({ limit: 1 });

for await (const page of prompts) {
  console.log('Connection successful!');
  console.log('Found', page.data?.length ?? 0, 'prompts');
}
```

## What's Exported

### Main entry point

```typescript theme={null}
import {
  Mutagent,           // Main client class
  SDKOptions,         // Client configuration type
  HTTPClient,         // Custom HTTP client interface
} from '@mutagent/sdk';
```

### Error types

```typescript theme={null}
import {
  MutagentError,            // Base error class for all HTTP errors
  SDKError,                 // Fallback error (unmatched status codes)
  SDKValidationError,       // Request validation errors
  ResponseValidationError,  // Response validation errors
} from '@mutagent/sdk/models/errors';
```

### Tracing (separate subpath export)

```typescript theme={null}
import {
  initTracing,
  shutdownTracing,
  trace,
  withTrace,
  startSpan,
  endSpan,
} from '@mutagent/sdk/tracing';
```

### Models and operations

```typescript theme={null}
import * as models from '@mutagent/sdk/models';
import * as operations from '@mutagent/sdk/models/operations';
```