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

# 使用 Node.js SDK 运行

> 使用 @fetch-hive/sdk 包从 Node.js 或 TypeScript 调用工作流部署

# 使用 Node.js SDK 运行

当你想从 Node.js 或 TypeScript 调用工作流部署时，请使用官方的 `@fetch-hive/sdk` 包。SDK 包装了公共的 [`POST /v1/workflow/invoke`](../api-reference/workflows/invoke) 端点，处理身份验证，并同时支持直接响应和回调投递。

## 安装

```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```

该 SDK 针对 Node.js 18+（使用全局 `fetch`），并附带 TypeScript 类型定义。

## 身份验证

将 `FETCH_HIVE_API_KEY` 环境变量设置为你的工作区 API 密钥：

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
```

或显式传入密钥：

```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```

有关如何创建和轮换密钥，请参阅 [API 密钥](../workspace/api-keys)。

## 基本示例

直接运行工作流部署。该调用会阻塞，直到工作流完成：

```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
});

console.log(run.status);
console.log(run.output);
```

请参阅 [直接响应结构](../api-reference/workflows/invoke#response)。

## 方法参考

| 字段           | 类型                                                    | 必填 | 描述                                                                  |
| ------------ | ----------------------------------------------------- | -- | ------------------------------------------------------------------- |
| `deployment` | `string`                                              | 是  | 工作流部署名称                                                             |
| `variant`    | `string`                                              | 否  | 部署变体名称                                                              |
| `inputs`     | `Record<string, unknown>`                             | 否  | **Start** 步骤定义的变量的键值对                                               |
| `async`      | `{ enabled: boolean, callback_url?: string }`         | 否  | 回调投递设置                                                              |
| `user`       | `string`                                              | 否  | 在 [用户跟踪](../user-tracking/overview) 中显示的不透明调用方标识符                   |
| `metadata`   | `Record<string, string \| number \| boolean \| null>` | 否  | 调用方定义的扁平元数据，用于审计和日志过滤。请参阅 [调用元数据](../user-tracking/invoke-metadata) |

## 处理响应

```typescript theme={null}
const run = await client.invokeWorkflow({
  deployment: 'my-workflow',
  variant: 'default',
});

console.log(run.status);       // "completed" | "failed" | "running" | "queued"
console.log(run.output);       // final workflow output
console.log(run.request_id);   // use this to look up the run in Logs
```

## 回调投递

传入一个 `async` 块以立即返回，并让 Fetch Hive 在运行完成时调用你的回调 URL：

```typescript theme={null}
const run = await client.invokeWorkflow({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { topic: 'State of enterprise AI in 2026' },
  async: { enabled: true, callback_url: 'https://example.com/callback' },
});

console.log('Queued:', run.status);
console.log('Webhook secret:', run.webhook_secret);
```

请保存 `webhook_secret`，以便你能验证传入回调的签名。请参阅 [回调投递与 Webhook 触发](./async-and-webhooks) 了解验证流程和签名负载结构。

## 配置

| 选项        | 默认值                              | 描述               |
| --------- | -------------------------------- | ---------------- |
| `apiKey`  | `process.env.FETCH_HIVE_API_KEY` | 来自仪表板的 Bearer 令牌 |
| `baseURL` | `https://api.fetchhive.com/v1`   | 覆盖 API 基础 URL    |

```typescript theme={null}
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
```

对于长时间运行的直接工作流请求，请优先使用 `async: { enabled: true, ... }`，而不是增加客户端超时时间。

## 错误

非 2xx 响应会抛出一个 `Error`，其消息包含状态码和响应体：

```typescript theme={null}
try {
  const run = await client.invokeWorkflow({
    deployment: 'my-workflow',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

有关工作流特有的失败案例，请参阅 [错误处理](./error-handling)；有关 HTTP 状态码含义，请参阅 [错误与速率限制](../api-reference/errors-and-rate-limits)。

## 链接

* [npm 上的软件包](https://www.npmjs.com/package/@fetch-hive/sdk)
* [GitHub 上的源码](https://github.com/Fetch-Hive/nodejs-sdk)

## 后续步骤

* [回调投递与 Webhook 触发](./async-and-webhooks) - 验证回调签名
* [使用 API 运行](./run-with-api) - 使用 cURL 的相同流程
* [使用 Python SDK 运行](./run-with-python-sdk)
* [使用 Ruby SDK 运行](./run-with-ruby-sdk)
* [使用 PHP SDK 运行](./run-with-php-sdk)
* [调用工作流](../api-reference/workflows/invoke) - 完整端点参考