# @codespar/api-types 中文文档

规范地址：https://npmcn.com/package/%40codespar/api-types/

版本：0\.5\.0
npm 元数据更新时间：2026-05-28T02:15:24.224Z
中文译文更新时间：2026-11-10T07:56:39.681Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codespar/api-types
原文对照：https://npmcn.com/package/%40codespar/api-types/?lang=original
项目主页：https://codespar.dev/
源码仓库：https://github.com/codespar/codespar-core

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

- 包体积（解压后）：91.3 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-04-24T02:03:12.973Z
- 最新版本发布：2026-05-06T21:20:35.368Z
- 近 30 天下载量：3221（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

CodeSpar管理层API(api.codespar.dev)的共享REST电线合同——Zod schemas + 推断类型Script

## 安装

```sh
npm install @codespar/api-types
```

也可以使用：`pnpm add @codespar/api-types`、`yarn add @codespar/api-types`、`bun add @codespar/api-types`

## README

# @ codespar/ api 类型

CodeSpar管理级API的共享REST电线合同 `api.codespar.dev`。 。 。 .

每个请求正文和响应形状被一一定义为Zod schema,从中推断出匹配的TypeScript类型. 两个后端( N)`codespar-enterprise`)和仪表板(`codespar-web`) 从这里导入——不再有手卷式镜像类型.

## 为什么

两个bug在一个48小时的窗口中被运出,因为web和后端独立重新声明了相同的响应类型:

-   新创建的 API 密钥作为“ Revoked ” 渲染(`revoked_at` 在创建响应中省略, 假定存在网络类型, `undefined !== null` 真实的.
-   API 密钥列表返回为空( 后端返回) `{ keys: [...] }`,网页解析 `data.api_keys`) (中文(简体) ).

这里的Schemas是真理的唯一来源. 解析取取边界的响应, 这些失败成为不可能 —— 丢失/ 重命名的字段在运行时抛出, 而不是渲染破损的 UI .

## 使用量

```ts
import {
  ApiKeyRowSchema,
  ListApiKeysResponseSchema,
  type ListApiKeysResponse,
} from "@codespar/api-types";

const res = await fetch("/v1/api-keys", { headers: { authorization: `Bearer ${token}` } });
const body: ListApiKeysResponse = ListApiKeysResponseSchema.parse(await res.json());
//    ^^^^ throws ZodError if the backend drifts
```

每个模块都输出方案(`FooSchema`)和推断类型(`Foo`) (中文(简体) ). 导入您需要的任意一边 .

## 覆盖范围

-   `api-keys` ——创建/列表/行
-   `projects` - 创建/更新/列表/行
-   `connections` ——创建/列表/行/webhook-secret 旋转
-   `servers` — 列表/行 / auth-schema
-   `sessions` ——创建/列表/行/细节/工具调用/执行

### `auth_type` 语句

一个连接 `auth_type` 确定如何储存证书 转交上游供应商。 截止到0.4.0,enum有6个 值 :

| 数值 | 用于 |
| --- | --- |
| `api_key` | 大多数供应商——阿萨斯,梅尔卡多·帕果,NFe.io,花纹等. |
| `path_secret` | Z-API风格的提供商,将证书嵌入到URL路径中,并带有相伴头. |
| `oauth` | 供应商需要OAuth流量(例如用户授权的集成). |
| `cert` | mTLS——BR开封银行飞行员(BB活;Itaú / Santander / Bradesco / Caixa next). |
| `hmac_signed` | Foxbit + LATAM 加密交换器,用所衍生的HMAC来签名每个请求. |
| `none` | 公共APIs / 没有证书. |

### 0.4.0中有什么新鲜事

添加 `cert` 财务报告和审定财务报表 `hmac_signed` `auth_type` 连接的值 计划——合同现在涵盖BR开放式银行式mTLS飞行员和 HMAC签名的加密交换 API 与最初的4.

> **已知所限.** `AuthSchemaFieldKindSchema` (单位:千美元) `kind` 语句 对于一个认证计划中的单个字段)尚不包括 `hmac` - 只有连接级别 `auth_type` 恩姆会的 这个 仪表板 `ProviderConnectModal` 通过标记来工作 HMAC 签名的字段为 `path_secret` 有点 消费者阅读认证 计划应该直接预料这种不匹配,直到将来的未成年人 碰碰会收紧野外的药.

## 版本

-   此软件包反映了 `/v1/*` REST 表面为 `api.codespar.dev`。 。 。 .
-   附加变化(新字段,新终点计划) → 小起伏.
-   分解变化(去地取出,类型收缩) → 相接后端放出的同时运出大起落.

保持TS + Python +后端对齐——漂移是打破信任最响亮的方式.

## 还需要吗?

需要治理、预算限制和代理付款的审计线索? **[代码Spar 企业](https://codespar.dev/enterprise)** 在这些MCP服务器上添加了政策引擎,支付路由,以及合规模板.

## 许可证

麻省理工学院 - [代码.dev](https://codespar.dev/)

## 常见问题

### @codespar/api-types 是什么？

CodeSpar管理层API\(api\.codespar\.dev\)的共享REST电线合同——Zod schemas \+ 推断类型Script

### 如何安装 @codespar/api-types？

在项目目录运行 npm install @codespar/api-types，或使用 pnpm add / yarn add / bun add。

### @codespar/api-types 支持 TypeScript 吗？

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

### @codespar/api-types 支持 ESM 还是 CommonJS？

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

### @codespar/api-types 需要什么版本的 Node\.js？

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

### @codespar/api-types 可以商用吗？

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

### @codespar/api-types 的下载量有多少？

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

### @codespar/api-types 还在维护吗？

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