TypeScript SDK 參考

DataGen TypeScript SDK 的完整 API 參考

​

安裝

npm

npm install @datagen-dev/typescript-sdk

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

​

用戶端設定

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 工具。

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 端點。

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

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

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

const result = await client.getCustomTool(deploymentUuid: string): Promise<DeploymentDetails>

​

listCustomTools

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

---

​

自訂工具執行

​

runCustomTool

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

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

​

runCustomToolAsync

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

const result = await client.runCustomToolAsync(
    deploymentUuid: string,
    inputVars?: Record<string, any>,
    executionTimeout?: number    // 預設：120
): Promise<{ runUuid: string, status: "pending" }>

​

checkRunStatus

const result = await client.checkRunStatus(runUuid: string): Promise<RunStatus>

​

getRun

const result = await client.getRun(runUuid: string): Promise<RunResult>

​

waitForRun

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

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

---

​

Secret 管理

​

listSecrets

const result = await client.listSecrets(): Promise<SecretMetadata[]>

​

setSecret

const result = await client.setSecret({
    name: string,
    value: string,
    displayName?: string,
    description?: string,
    category?: string,     // 預設："api_key"
    force?: boolean,       // 預設：false
}): Promise<SecretMetadata>

---

​

錯誤類型

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

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