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

# TypeScript SDK Reference

> Complete API reference for the DataGen TypeScript SDK

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @datagen-dev/typescript-sdk
  ```

  ```bash yarn theme={null}
  yarn add @datagen-dev/typescript-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @datagen-dev/typescript-sdk
  ```
</CodeGroup>

Requires Node.js 18+ and TypeScript 5.0+.

## Client Configuration

```typescript theme={null}
import { DatagenClient } from '@datagen-dev/typescript-sdk';

const client = new DatagenClient({
    apiKey: undefined,       // Default: reads from DATAGEN_API_KEY env var
    baseUrl: "https://api.datagen.dev",
    timeout: 30000,          // Request timeout in ms
    retries: 0,              // Retry attempts for failed requests
    backoffSeconds: 0.5      // Initial backoff for retries
});
```

| Parameter        | Type      | Default                     | Description                                      |
| ---------------- | --------- | --------------------------- | ------------------------------------------------ |
| `apiKey`         | `string?` | `undefined`                 | API key. Falls back to `DATAGEN_API_KEY` env var |
| `baseUrl`        | `string`  | `"https://api.datagen.dev"` | DataGen API base URL                             |
| `timeout`        | `number`  | `30000`                     | Request timeout in milliseconds                  |
| `retries`        | `number`  | `0`                         | Number of retry attempts                         |
| `backoffSeconds` | `number`  | `0.5`                       | Initial backoff time for retries                 |

***

## Tool Execution

### `executeTool`

Execute an MCP tool by its alias name.

```typescript theme={null}
const result = await client.executeTool(
    toolAliasName: string,
    parameters?: Record<string, any>
): Promise<any>
```

| Parameter       | Type                  | Required | Description                                       |
| --------------- | --------------------- | -------- | ------------------------------------------------- |
| `toolAliasName` | `string`              | Yes      | Tool alias (e.g., `"mcp_Gmail_gmail_send_email"`) |
| `parameters`    | `Record<string, any>` | No       | Tool-specific parameters                          |

**Returns:** Tool execution result.

**Throws:** `DatagenAuthError`, `DatagenToolError`, `DatagenHttpError`

***

## Custom Tool Deployment

### `deployCustomTool`

Deploy a Python workflow as an API endpoint.

```typescript theme={null}
const result = await client.deployCustomTool({
    name: string,
    code: string,
    description?: string,
    inputSchema?: Record<string, any>,
    outputVars?: string[],
    expectedTools?: string[],
    additionalImports?: string[],
    deploymentType?: "private" | "public",
    defaultInputVars?: Record<string, any>,
    mcpServerNames?: string[],
    requiredSecrets?: string[],
}): Promise<DeploymentResult>
```

| Parameter           | Type       | Required | Default     | Description                    |
| ------------------- | ---------- | -------- | ----------- | ------------------------------ |
| `name`              | `string`   | Yes      | --          | API name for the tool          |
| `code`              | `string`   | Yes      | --          | Python code to deploy          |
| `description`       | `string`   | No       | --          | Tool description               |
| `inputSchema`       | `object`   | No       | --          | OpenAPI/JSON Schema for inputs |
| `outputVars`        | `string[]` | No       | --          | Output variable names          |
| `expectedTools`     | `string[]` | No       | --          | Required MCP tools             |
| `additionalImports` | `string[]` | No       | --          | Python packages                |
| `deploymentType`    | `string`   | No       | `"private"` | `"private"` or `"public"`      |
| `defaultInputVars`  | `object`   | No       | --          | Default input values           |
| `mcpServerNames`    | `string[]` | No       | --          | MCP server names               |
| `requiredSecrets`   | `string[]` | No       | --          | Required secret names          |

**Returns:** Object with `deploymentUuid` and deployment details.

**Throws:** `DatagenDeploymentError`

### `updateCustomTool`

Update an existing custom tool. Only provided fields are updated.

```typescript theme={null}
const result = await client.updateCustomTool(
    deploymentUuid: string,
    updates: {
        name?: string,
        description?: string,
        code?: string,
        inputSchema?: Record<string, any>,
        outputVars?: string[],
        defaultInputVars?: Record<string, any>,
        additionalImports?: string[],
        expectedTools?: string[],
        requiredSecrets?: string[],
    }
): Promise<DeploymentResult>
```

### `getCustomTool`

```typescript theme={null}
const result = await client.getCustomTool(deploymentUuid: string): Promise<DeploymentDetails>
```

### `listCustomTools`

```typescript theme={null}
const result = await client.listCustomTools({
    sortBy?: string,    // Default: "created_at"
    orderBy?: string,   // Default: "desc"
    skip?: number,      // Default: 0
    limit?: number,     // Default: 100
}): Promise<DeploymentDetails[]>
```

***

## Custom Tool Execution

### `runCustomTool`

Run synchronously (blocks until complete).

```typescript theme={null}
const result = await client.runCustomTool(
    deploymentUuid: string,
    inputVars?: Record<string, any>,
    executionTimeout?: number    // Default: 120
): Promise<RunResult>
```

### `runCustomToolAsync`

Run asynchronously (returns immediately).

```typescript theme={null}
const result = await client.runCustomToolAsync(
    deploymentUuid: string,
    inputVars?: Record<string, any>,
    executionTimeout?: number    // Default: 120
): Promise<{ runUuid: string, status: "pending" }>
```

### `checkRunStatus`

```typescript theme={null}
const result = await client.checkRunStatus(runUuid: string): Promise<RunStatus>
```

### `getRun`

```typescript theme={null}
const result = await client.getRun(runUuid: string): Promise<RunResult>
```

### `waitForRun`

Poll until an async run completes.

```typescript theme={null}
const result = await client.waitForRun(
    runUuid: string,
    timeout?: number,        // Default: 300
    pollInterval?: number    // Default: 2.0
): Promise<RunResult>
```

***

## Secret Management

### `listSecrets`

```typescript theme={null}
const result = await client.listSecrets(): Promise<SecretMetadata[]>
```

### `setSecret`

```typescript theme={null}
const result = await client.setSecret({
    name: string,
    value: string,
    displayName?: string,
    description?: string,
    category?: string,     // Default: "api_key"
    force?: boolean,       // Default: false
}): Promise<SecretMetadata>
```

***

## Error Types

```typescript theme={null}
import {
    DatagenClient,
    DatagenError,
    DatagenAuthError,
    DatagenToolError,
    DatagenHttpError,
    DatagenDeploymentError,
    DatagenSecretError,
} from '@datagen-dev/typescript-sdk';
```

| Exception                | Description                     |
| ------------------------ | ------------------------------- |
| `DatagenError`           | Base exception class            |
| `DatagenAuthError`       | Authentication failed (401/403) |
| `DatagenToolError`       | Tool execution failed           |
| `DatagenHttpError`       | HTTP-level errors               |
| `DatagenDeploymentError` | Deployment or run failed        |
| `DatagenSecretError`     | Secret management errors        |