# @cat-factory/sdk 中文文档

规范地址：https://npmcn.com/package/%40cat-factory/sdk/

版本：0\.68\.0
npm 元数据更新时间：2026-11-04T00:26:46.361Z
中文译文更新时间：2026-11-09T07:30:04.386Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cat-factory/sdk
原文对照：https://npmcn.com/package/%40cat-factory/sdk/?lang=original
源码仓库：https://github.com/kibertoad/cat-factory

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：750 kB，35 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-08-04T13:40:21.533Z
- 最新版本发布：2026-11-04T00:26:45.821Z
- 近 30 天下载量：4100（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

TypeScript/JavaScript 客户端,用于 Cat-factory 公共 API (/api/v1): 由已公布的 OpenAPI spec 生成的已键模式和资源客户端, 以手写方式传送无记名证书、 绑定重试、 密钥集自动插图和 SSE 重用

## 安装

```sh
npm install @cat-factory/sdk
```

也可以使用：`pnpm add @cat-factory/sdk`、`yarn add @cat-factory/sdk`、`bun add @cat-factory/sdk`

## README

# `@cat-factory/sdk`

用于 Cat- 构件的 TypeScript / JavaScript 客户端 **公开 API** (单位:千美元)`/api/v1`) (中文(简体) ).

```sh
npm install @cat-factory/sdk
```

节点20+. 无依赖关系:运输是 `fetch`。 。 。 .

```ts
import { CatFactoryClient, CatFactoryNotFoundError } from '@cat-factory/sdk'

const client = new CatFactoryClient({
  baseUrl: 'https://cat-factory.example.com',
  apiKey: process.env.CAT_FACTORY_API_KEY!,
})

const { services } = await client.services.list()
const task = await client.tasks.create(services[0].serviceId, {
  title: 'Add a health check endpoint',
  taskType: 'feature',
})
await client.tasks.start(task.taskId, {})
```

## 资源客户

`jobs`, (中文(简体) ), `services`, (中文(简体) ), `tasks`, (中文(简体) ), `pipelines`, (中文(简体) ), `notifications`, (中文(简体) ), `webhook`, (中文(简体) ), `usage`, (中文(简体) ), `decisions`, (中文(简体) ), `debug`数字 : 已公布的 OpenAPI 表面的每个标签 。 工作空间范围呼叫在键唯一的工作空间上,或者在 `workspaceId` 对于一个键 达到数.

## 看着跑步

```ts
const stream = await client.tasks.stream(task.taskId)
try {
  for await (const event of stream) {
    if (event.event === 'decision') {
      // The run PARKED on a human decision and waits indefinitely. Answer it through
      // `client.decisions` (needs a `decide`-scope key) or free it with `tasks.stop`.
      const { decisions } = await client.decisions.list(runId)
    }
    if (event.event === 'done' || event.event === 'error') break
    // `timeout` means the deployment's connection cap was reached, NOT that the run finished.
  }
} finally {
  await stream.close()
}
```

## 拨号

每个被绑定的列表都有一个自动显示的伴奏 `nextCursor` 为你:

```ts
for await (const task of client.tasks.listByServiceAll(serviceId)) {
  console.log(task.taskId)
}
```

## 错误

例外的CLAS来自HTTP状态; `code` 带着具体事业,是平地 字符串,因为这个表面添加了没有主要版本的新代码.

```ts
try {
  await client.tasks.get(taskId)
} catch (error) {
  if (error instanceof CatFactoryNotFoundError) return null
  if (error instanceof CatFactoryForbiddenError && error.code === 'insufficient_scope') {
    throw new Error('this key needs a higher scope')
  }
  throw error
}
```

类 : `CatFactoryValidationError` (400/422) (中文(简体) ), `…Unauthorized` (401个), `…Forbidden` (403个), `…NotFound` (404个), `…Conflict` (409个), `…CredentialRequired` (428个), `…RateLimited` (429个), `…ServerError` (5xx),加上: `…ConnectionError`, (中文(简体) ), `…TimeoutError` 财务报告和审定财务报表 `…DecodeError`全部扩展 `CatFactoryError`。每个 API 错误都包含 `status`, (中文(简体) ), `code`, (中文(简体) ), `details`, (中文(简体) ), `issues` 编辑 `requestId` 在报告过失时引用.

A 类 `CatFactoryConnectionError` 说明实际失败,而不是声称部署 无法接触,并说出这个客户已经从来源看到的东西:

```text
cat-factory SDK: POST /api/v1/tasks failed: https://cat-factory.example.com reset the connection
before answering. This client had answered 9 calls against https://cat-factory.example.com, the
last 0.2s ago. (read ECONNRESET)
```

在九次接通电话后重设是重新启动的部署;拒绝无一答复 却是一个没有背后的地址 两个人把你送到完全不同的地方 这个 运行时间本身的起因链在消息的结尾和运行时保持逐字记录 `cause`。 。 。 .

## 选项

```ts
new CatFactoryClient({
  baseUrl,
  apiKey,
  timeoutMs: 30_000, // 0 disables
  maxRetries: 2, // idempotent requests only - a POST is never auto-retried
  headers: {},
  userAgent: 'my-integration/1.2.3',
  fetch: myFetch, // a proxy agent, or a test double
})
```

## 地方发展和嘲笑

基础 URL 具有任何来源( Name`http://localhost:8787`,固定服务器,模拟器),没有方案 进行验证。 每个客户端也接受自定义运输,这样您就可以在进程内拦截 换句话说 见 [sDK 指南](https://www.catfactory.ai/extend/sdks.html#pointing-a-client-at-localhost-or-a-mock)。 。 。 .

## 页:1

-   `src/*.generated.ts` 从 `docs/openapi.json`; 见 [`../README.md`](https://github.com/kibertoad/cat-factory/blob/main/sdk/README.md)。 。 。 .
-   来源是 **仅可删除** TypeScript (没有enum, 命名空间或参数属性), 所以 他们运行在节点的类型剥离和 `erasableSyntaxOnly` 建设.
-   API 参考 : [`backend/docs/public-api.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/public-api.md)。 。 。 .

## 常见问题

### @cat-factory/sdk 是什么？

TypeScript/JavaScript 客户端,用于 Cat-factory 公共 API \(/api/v1\): 由已公布的 OpenAPI spec 生成的已键模式和资源客户端, 以手写方式传送无记名证书、 绑定重试、 密钥集自动插图和 SSE 重用

### 如何安装 @cat-factory/sdk？

在项目目录运行 npm install @cat-factory/sdk，或使用 pnpm add / yarn add / bun add。

### @cat-factory/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cat-factory/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cat-factory/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cat-factory/sdk 可以商用吗？

@cat-factory/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cat-factory/sdk 的下载量有多少？

根据 npm 官方下载统计，@cat-factory/sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 4,100 次，日均约 137 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cat-factory/sdk 还在维护吗？

最新版本 0\.68\.0 发布于 2026/11/04（5 天前）；至今共发布 82 个版本，其中过去 12 个月发布了 82 个；首次发布于 2026/08/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。