> ## 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 參考

> DataGen TypeScript SDK 的完整 API 參考

## 安裝

<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>

需要 Node.js 18 以上與 TypeScript 5.0 以上版本。

## 用戶端設定

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

const client = new DatagenClient({
    apiKey: undefined,       // 預設：從 DATAGEN_API_KEY 環境變數讀取
    baseUrl: "https://api.datagen.dev",
    timeout: 30000,          // 請求逾時（毫秒）
    retries: 0,              // 請求失敗時的重試次數
    backoffSeconds: 0.5      // 重試的初始退避時間
});
```

| 參數 | 型別 | 預設值 | 說明 |
| - | - | - | - |
| `apiKey` | `string?` | `undefined` | API key。未提供時改用 `DATAGEN_API_KEY` 環境變數 |
| `baseUrl` | `string` | `"https://api.datagen.dev"` | DataGen API base URL |
| `timeout` | `number` | `30000` | 請求逾時（毫秒） |
| `retries` | `number` | `0` | 重試次數 |
| `backoffSeconds` | `number` | `0.5` | 重試的初始退避時間 |

***

## 工具執行

### `executeTool`

以別名執行 MCP 工具。

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

| 參數 | 型別 | 必填 | 說明 |
| - | - | - | - |
| `toolAliasName` | `string` | 是 | 工具別名（例如 `"mcp_Gmail_gmail_send_email"`） |
| `parameters` | `Record<string, any>` | 否 | 工具專屬參數 |

**回傳：** 工具執行結果。

**例外：** `DatagenAuthError`、`DatagenToolError`、`DatagenHttpError`

***

## 自訂工具部署

### `deployCustomTool`

將 Python 工作流程部署為 API 端點。

```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>
```

| 參數 | 型別 | 必填 | 預設值 | 說明 |
| - | - | - | - | - |
| `name` | `string` | 是 | -- | 工具的 API 名稱 |
| `code` | `string` | 是 | -- | 要部署的 Python 程式碼 |
| `description` | `string` | 否 | -- | 工具說明 |
| `inputSchema` | `object` | 否 | -- | 輸入的 OpenAPI/JSON Schema |
| `outputVars` | `string[]` | 否 | -- | 輸出變數名稱 |
| `expectedTools` | `string[]` | 否 | -- | 需要的 MCP 工具 |
| `additionalImports` | `string[]` | 否 | -- | Python 套件 |
| `deploymentType` | `string` | 否 | `"private"` | `"private"` 或 `"public"` |
| `defaultInputVars` | `object` | 否 | -- | 預設輸入值 |
| `mcpServerNames` | `string[]` | 否 | -- | MCP server 名稱 |
| `requiredSecrets` | `string[]` | 否 | -- | 需要的 secret 名稱 |

**回傳：** 含 `deploymentUuid` 與部署細節的物件。

**例外：** `DatagenDeploymentError`

### `updateCustomTool`

更新既有的自訂工具。只會更新有提供的欄位。

```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,    // 預設："created_at"
    orderBy?: string,   // 預設："desc"
    skip?: number,      // 預設：0
    limit?: number,     // 預設：100
}): Promise<DeploymentDetails[]>
```

***

## 自訂工具執行

### `runCustomTool`

以同步方式執行（會等待執行完成）。

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

### `runCustomToolAsync`

以非同步方式執行（立即回傳）。

```typescript theme={null}
const result = await client.runCustomToolAsync(
    deploymentUuid: string,
    inputVars?: Record<string, any>,
    executionTimeout?: number    // 預設：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`

持續輪詢，直到非同步執行完成。

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

***

## Secret 管理

### `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,     // 預設："api_key"
    force?: boolean,       // 預設：false
}): Promise<SecretMetadata>
```

***

## 錯誤類型

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

| 例外 | 說明 |
| - | - |
| `DatagenError` | 基礎例外類別 |
| `DatagenAuthError` | 身分驗證失敗（401/403） |
| `DatagenToolError` | 工具執行失敗 |
| `DatagenHttpError` | HTTP 層級錯誤 |
| `DatagenDeploymentError` | 部署或執行失敗 |
| `DatagenSecretError` | Secret 管理錯誤 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.