# @cocreate/api 中文文档

规范地址：https://npmcn.com/package/%40cocreate/api/

版本：2\.1\.2
npm 元数据更新时间：2026-11-07T02:39:10.501Z
中文译文更新时间：2026-11-10T06:59:16.919Z
软件包许可：GPL-3\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cocreate/api
原文对照：https://npmcn.com/package/%40cocreate/api/?lang=original
项目主页：https://cocreatejs.com/docs/api
源码仓库：https://github.com/CoCreateJS/api

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

- 包体积（解压后）：255 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2021-01-24T04:11:27.609Z
- 最新版本发布：2026-11-07T02:39:10.313Z
- 近 30 天下载量：2530（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：277（近 12 个月 15 个）

## 中文简介

一个安全,多租借的API执行网关和代理层,能动态地解决端点动作,处理AST微操作器,处理webhooks,在严格的租户环境隔离下管理第三方整合.

## 安装

```sh
npm install @cocreate/api
```

也可以使用：`pnpm add @cocreate/api`、`yarn add @cocreate/api`、`bun add @cocreate/api`

## README

# 创建/ api

一个动态的,多租借的API执行网关,代理引擎,和Webhook管弦乐路由层. 它安全地管理分布式集成架构,允许应用程序配置,评价,并执行复杂的第三方API配置和多步骤的苍蝇上宏工作流程. 将抽象语法树(AST)评价沙盒(`NativeSandbox`)在严格租户环境隔离的情况下,它将申报配置转变为低纬度外出集成,并在不引入跨租户数据泄露的情况下安全地入网.

包装船都把一体化减半。 在客户端上,第三方API通过HTML5属性或通过等同的JavaScript API进行声明消费. 在服务器上,网关解决了证书,评价了配置,并执行出局请求,因此API密钥从未到达浏览器.

* * *

## 文档

完整 API 参考文献、集成指南、网页浏览配置和使用示例,请访问 **[创建 API 文档](https://cocreatejs.com/docs/api)**。 。 。 .

## 目录

-   [文档](https://npmcn.com/package/%40cocreate/api/#readme-documentation)
-   [特征](https://npmcn.com/package/%40cocreate/api/#readme-features)
-   [动态操作沙盒](https://npmcn.com/package/%40cocreate/api/#readme-dynamic-operations-sandbox)
-   [安装](https://npmcn.com/package/%40cocreate/api/#readme-installation)
-   [客户端使用: HTML5 属性](https://npmcn.com/package/%40cocreate/api/#readme-client-usage-html5-attributes)
-   [客户端使用: JavaScript API](https://npmcn.com/package/%40cocreate/api/#readme-client-usage-javascript-api)
-   [属性参考](https://npmcn.com/package/%40cocreate/api/#readme-attribute-reference)
-   [服务器使用](https://npmcn.com/package/%40cocreate/api/#readme-usage)
-   [如何运作](https://npmcn.com/package/%40cocreate/api/#readme-how-it-works)
-   [结构和有效载荷光谱](https://npmcn.com/package/%40cocreate/api/#readme-architecture-and-payload-specs)
-   [安全执行](https://npmcn.com/package/%40cocreate/api/#readme-security-implementations)
-   [如何贡献](https://npmcn.com/package/%40cocreate/api/#readme-how-to-contribute)
-   [许可证](https://npmcn.com/package/%40cocreate/api/#readme-license)

* * *

## 特征

-   **抽象语法树 (AST) 微操作器:** 评估函数配置内在语境,支持表达式语法标记(如 `$data`, (中文(简体) ), `$event`, (中文(简体) ), `$actions`,以及 `$request`)和自定义商业逻辑操作员.
-   **声明客户界面 :** 配置使用 HTML5 属性的完整请求和响应周期,从窗体字段组装有效载荷并映射结果回到文档中,而无需指定提供者代码.
-   **租户环境隔离防火墙:** 通过拦截执行矩阵和强行注射捆绑,保证加密数据分割 `organization_id` 并核实 `host` 将数值输入核心操作.
-   **实时 WebSocket 集成矩阵 :** 无缝钩入活服务器网络(`wsManager`),倾听来信 `api` 财务报告和审定财务报表 `endpoint` 动作和流出实时运行状态有效载荷直接返回客户端.
-   **双出行矢量:** 线速原生地,预构造的HTTP有效载荷即时,或动态地构建自定义多步骤的出行集成,通过解决运行时元数据与持久性层.
-   **密码签名和 JWT 管弦乐:** 特性 原生,低纬度的钩子生成 JSON Web Tokens(`$jwt`使用HMAC-SHA256,同时进行定时攻击安全网络标记验证(`verifySignature`) (中文(简体) ).
-   **封存 AST 运行时 sandbox :** 具有硬化的公用基质,包含有沙箱的全球物体(`JSON`, (中文(简体) ), `Array`, (中文(简体) ), `Math`)和帮助方法(如 Base64 编码/解码和 URL 编码器),安全地将计算包裹在全球范围之外.
-   **本地边缘流检查 :** 自动检查主动服务器响应缓冲器, 无法返回干净的 200 OK 只有当宏管道没有强制完成或关闭流时才确定 .

* * *

## 动态操作沙盒

引擎使用预定义的沙盒层来评价标准属性和自定义功能变量. 这使得配置配置配置可以安全地从苍蝇上取出字段.

| 核心运算符范围 | 提取出源值 |
| --- | --- |
| **`$data`** | 从主动输入执行有效载荷中提取标准关键参数(`data`) (中文(简体) ). |
| **`$event`** | 解析通过活性 Webhook 流传输的 JSON 原始输入参数 . |
| **`$actions`** | 从之前的大型管线链路展出了一系列历史执行文物. |
| **`$request` 编号 : `$header`** | HTTP 下方的曝光请求属性,方法和入网参数. |
| **`$jwt`** | 触发一个活动加密签名循环,从属性中创建安全的 JWT 令牌 . |

* * *

## 安装

```bash
npm install @cocreate/api
```

* * *

## 使用量

API引擎消耗有两种方式. 在客户端上,集成完全以HTML5属性声明或通过JavaScript API驱动. 在服务器上,网关会解析证书,评价配置,并实现出站请求.

* * *

## 客户端使用: HTML5 属性

客户端不需要提供商特定代码. 在集装箱上宣布供应商登记,每个含有供应商属性的元素都会为外出有效载荷提供场或从反应中接收场.

### 宣布提供者

```html
<form api="stripe"></form>
```

价值 `api` 是供货商名称。 它成为了每个字段使用的属性前缀,用于触发请求的动作名,以及发送到套接字上的有效载荷密钥. `module` 被接受为别名.

### 构建请求

每个参与元素都声明它所属的方法和所居路径.

```html
<form api="stripe">
    <input stripe="customers.create" stripe-key="email" />
    <input stripe="customers.create" stripe-key="metadata.workspace" value="production" hidden />

    <button actions="stripe.customers.create">Create customer</button>
</form>
```

单击按钮收集每个 `[stripe="customers.create"]` 元件的形式,读取每个值,从中组装有效载荷 `stripe-key` 路径 :

```json
{
    "method": "stripe.customers.create",
    "stripe": {
        "email": "developer@CoCreateJS.com",
        "metadata": { "workspace": "production" }
    },
    "status": "await"
}
```

键用点符号表示巢穴,用括号表示指数,所以 `messages[0].content` 财务报告和审定财务报表 `metadata.workspace` 两种决心都与嵌入物有关。 密钥结尾于 `[]` 添加到数组中,允许多个元素为同一集合提供条目.

### 收到回复

标记元素 `-request="false"` 被排除在外出有效载荷之外,并且仅用于从反应中获得价值.

```html
<input
    stripe="customers.create"
    stripe-key="id"
    stripe-request="false"
    hidden />
```

当响应到达时,该路径的值被写入元素. 使用 `-response="false"` 以反向的方式:一个被派遣而永不覆写的地方。 键 `{}` 绘制整个提供者的有效载荷而不是单一路径.

### 链条结果

由于反应是用标准值管道来写出,任何绑定模块都可以对此作出反应.

```html
<input
    stripe="customers.create"
    stripe-key="id"
    stripe-request="false"
    input-query="$document #customer-id"
    input.value="$value"
    hidden />
```

### 选择触发器

默认情况下,请求只在动作起火时运行. `-event` 将元素选择为附加触发.

```html
<input
    currency="rates.read"
    currency-key="base"
    currency-event="input, onload" />
```

可用的触发类型是 `action`, (中文(简体) ), `input`, (中文(简体) ), `onload`, (中文(简体) ), `nodeObserver`,以及 `attributeObserver`。 。 。 .

### 范围和终点

从最近的祖先收集字段 `form`,或者从文档中,当元素不在其中之一时,那么几个独立的集成可以在一页并存. a 内的要素 `[template]` 被跳过,保留模板 从活有效载荷.

一个 `endpoint` 属性选择已配置的路由,并 a `query` 属性标记请求为查询.

```html
<input stripe="customers.create" endpoint="POST /v1/customers" hidden />
```

### 渲染出错

当网关返回出错时,客户端会将其制成匹配提供者名称的任何模板,接收 `type`, (中文(简体) ), `method`, (中文(简体) ), `status`,以及 `message`。 。 。 .

```html
<div template="stripe-error">{{message}}</div>
```

* * *

## 客户端使用: JavaScript API

在方案方面,对于需要登记选择权、自定义处理器或必须执行的供应商,也提供同样的管道.

### 注册a 提供者

```javascript
import api from "@cocreate/api";

api.init({
    name: "stripe",
    endPoints: {},
    options: { socket: true }
});
```

通话 `init()` 没有参数则扫描文档 `[api]` 财务报告和审定财务报表 `[module]` 元素并注册每个供应商。 除非 `options.socket` 实值 `false`。 。 。 .

### 执行请求

```javascript
api.request({
    name: "stripe",
    method: "customers.create",
    form: document.querySelector("#billing"),
    type: "action"
});
```

### 直接使用有效载荷

```javascript
const data = await api.getData({
    name: "stripe",
    method: "customers.create",
    form: document.querySelector("#billing")
});

await api.send({ name: "stripe", method: "customers.create", data });
```

`send()` 通过 C创造套接字传输为 `provider.method` 在将有效载荷映射到文件之前等待相关反应.

### 自定义处理器

如果注册模块定义了方法的处理器,则其 `request` 财务报告和审定财务报表 `response` 函数优先于默认的收集和绘图行为。 这是供应商需要点名序列化的扩展点,例如第三方SDK元素.

* * *

## 服务器使用

### 模块初始化

在您核心的拖曳阶段直接捆绑 API 框架 `CoCreateServer` 应用程序矩阵.

```javascript
import apiGateway from '@cocreate/api';
import { CoCreateServer } from '@cocreate/cluster';

// Boot the primary application server instance
const serverContext = await CoCreateServer.start();

// Initialize the API engine and register WebSocket listeners
await apiGateway.init(serverContext);
```

### 直接程序化 API 执行

使用统一的集成对象执行复杂的第三方出行宏操作.

```javascript
import apiGateway from '@cocreate/api';

// The method identifies the provider credentials, and the endpoint resolves the data model
const payload = {
  organization_id: "64b9a32e18f21bc56789abcd",
  method: "stripe",
  endpoint: "POST /v1/customers",
  stripe: {
    email: "$data.userEmail",
    metadata: {
      workspace: "production"
    }
  },
  userEmail: "developer@CoCreateJS.com"
};

const result = await apiGateway.executeApi(payload);
```

* * *

## 属性参考

`name` 指经下列机构申报的提供者: `api` 属性,例如 `stripe` 或者说 `openai`。 。 。 .

| 属性 | 作用 |
| --- | --- |
| `api="name"` | 申报并登记提供者. `module` 是公认的别名. |
| `name="method"` | 标出该元素作为该方法请求和响应的参与者. |
| `name-key="path"` | 路径元素填充或接收 。 支持点和括号符号, `[]` 附加到数组中,以及 `{}` 整个有效载荷. |
| `name-event="types"` | 执行请求的触发类型 : `action`, (中文(简体) ), `input`, (中文(简体) ), `onload`, (中文(简体) ), `nodeObserver`, (中文(简体) ), `attributeObserver`默认为 `action`。 。 。 . |
| `name-request="false"` | 将元素排除在外出有效载荷之外,使其仅能作出反应. |
| `name-response="false"` | 将元素从响应映射中排除出,使其成为仅请求. |
| `endpoint="METHOD /route"` | 设置网关解决的终点. |
| `query` | 将请求标为查询. |
| `template_id="id"` | 通过匹配模板而不是设置值来渲染响应. |
| `actions="name.method"` | 触发请求并参与动作链. |

### 页:1

-   田地来自最近的祖先 `form`,回到文档.
-   A 内的要素 `[template]` 不包括在有效载荷收集中.
-   携带 `actions` 属性在响应映射时被跳过,这样链条行为就不会被覆盖.
-   发送请求时取消了广播,因此有效载荷从未被其他客户所响应.

* * *

## 如何运作

1.  **绑定靴子事件( E) :** 期间 `init()`,模块会直接连接到服务器的 WebSocket 框架(`wsManager`),捕获来信 `api` 财务报告和审定财务报表 `endpoint` 事件信号可以引导它们到执行处理器.
2.  **背景和防火墙初始化:** 对于每次出行执行,引擎都会根据母上下文防火墙评价参数. 安全配置配置匹配已验证的套接字边框的输入连接, 锁定 `organization_id` 财务报告和审定财务报表 `host` 配置.
3.  **宏配置解析 :** 引擎通过 CRUD 同步层发送查询,以匹配存储端点或数据库库内活性集成细节的配置文件.
4.  **AST 矩阵处理 :** 路由器通过 `processOperators()`。找到匹配活动变量的字符串(例如 `$` 前缀)被安全地编译于孤立的 `NativeSandbox` 环境.
5.  **输出网络获取 :** 系统构建请求配置文件, 强力设置内容标题, 映射 a `AbortController` 超时断路器( 15秒截取) , 并使用运行时的本地端执行请求 `fetch` 执行.
6.  **有效载荷发送和 Webhook 调度 :** Webhook 目标匹配入围边缘规则验证安全值,按顺序执行配置的工作流程,并返回结构化响应.

* * *

## 结构和有效载荷光谱

### 统一有效载荷对象Schema

API引擎依赖于平坦的,可声明的有效载荷物体通过执行管道.

| 字段元素 | 类型 | 作用 |
| --- | --- | --- |
| `organization_id` | `String` | **要求.** 瞄准用于解决融合和证书问题的租户情况. |
| `method` | `String` | **要求.** 提供者身份(例如 `"stripe"`) (中文(简体) ). |
| `endpoint` | `String` | **要求.** HTTP 用于定位所配置的终点的方法和路由( 例如) `"POST /v1/customers"`) (中文(简体) ). |
| `[providerName]` | `Object` | 提供方特定输入对象(例如 `stripe`),通过AST引擎处理. |

### 上下文引擎参数Schema

API引擎为每个请求创建执行上下文.

| 字段元素 | 类型 | 作用 |
| --- | --- | --- |
| `data` | `Object` | 向执行管道提供输入有效载荷. |
| `event` | `Object` | 解析后网络hook请求体. |
| `actions` | `Array` | 以往工作流程步骤累积的成果. |
| `organization_id` | `String` | 租户身份标识. |
| `host` | `String` | 经核实的租户宿主用于隔离. |
| `crud` 编号 : `wsManager` | `Object` | 参考 CRUD 层和 WebSocket 管理器. |

* * *

## 安全执行

> \[尖叫声\] 父母执行上下文总是会超越收到的有效载荷值,以防止跨租户进入或特权升级.

### 上下文沙箱

内部服务,例如: `crud` 财务报告和审定财务报表 `wsManager` 截取执行论据并自动执行经认证的租户上下文。 即使恶意配置试图覆盖租户信息,运行时间也会以已核实的执行上下文取而代之.

### 时间和安全签字核查

装有认证规则的入网网络hooks 使用 `crypto.timingSafeEqual`\- 防止在签字核查期间发生时间攻击.

* * *

## 如何贡献

我们鼓励为所有创造图书馆捐款。 请看我们的 **[捐款额](https://github.com/CoCreateJS/api/blob/master/CONTRIBUTING.md)** 发展工作流程指南和贡献指南.

如果您发现一个错误或想要请求一个特性, 请打开我们的问题 **[GitHub 问题](https://github.com/CoCreateJS/api/issues)** 跟踪器.

关于完整的API文件、集成实例和网页浏览指南,访问:

[https://cocreatejs.com/docs/api 页面存档备份,存于互联网档案馆](https://cocreatejs.com/docs/api)

* * *

## 许可证

该软件在GNU Affero通用公共许可证版本3(AGPLv3)和商业许可证下获得双许可证.

-   **开源使用 :** 对于开源项目和非商业用途,该软件可在AGPLv3下提供. 许可证全文见LICENSE文件.
-   **商业用途:** 商业用户必须取得商业许可证。 商业许可证通过创造平台在注册API密钥时提供.

## HTTP 入口

初始化的API服务曝光 `http(req, res)` 并行 `webhook(req, res)`。模块接受 POST JSON 机构,最多可达 1 MiB ,从主机名解析组织范围,并通过 `server.authorize.request` 处决前。 API 密钥和信封 `apikey` 字段被支持;冲突键被拒绝。 缺少许可或授权服务返回403。 呼叫器范围和 socket/用户身份不在此列,执行时使用无传送密钥的已消毒信封.

`send()` 仍然保留信任的内部呼叫和套接字发送所使用的执行 API , 而套接字的授权已经发生。 已存在的webhook AST拥有供应商签名验证.

## 常见问题

### @cocreate/api 是什么？

一个安全,多租借的API执行网关和代理层,能动态地解决端点动作,处理AST微操作器,处理webhooks,在严格的租户环境隔离下管理第三方整合\.

### 如何安装 @cocreate/api？

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

### @cocreate/api 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cocreate\_\_api 是否存在。

### @cocreate/api 支持 ESM 还是 CommonJS？

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

### @cocreate/api 可以商用吗？

@cocreate/api 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @cocreate/api 的下载量有多少？

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

### @cocreate/api 还在维护吗？

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