# @baack-software/baack-ts-client 中文文档

规范地址：https://npmcn.com/package/%40baack-software/baack-ts-client/

版本：0\.0\.12
npm 元数据更新时间：2026-11-03T16:08:09.742Z
中文译文更新时间：2026-11-07T22:25:14.229Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40baack-software/baack-ts-client
原文对照：https://npmcn.com/package/%40baack-software/baack-ts-client/?lang=original
项目主页：https://github.com/Baack-Software/baack-ts-client#readme
源码仓库：https://github.com/Baack-Software/baack-ts-client

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

- 包体积（解压后）：258 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-18T07:58:09.635Z
- 最新版本发布：2026-11-03T16:08:09.552Z
- 近 30 天下载量：2273（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Baack.co 无头 CMS 的官方TypeScript客户端

## 安装

```sh
npm install @baack-software/baack-ts-client
```

也可以使用：`pnpm add @baack-software/baack-ts-client`、`yarn add @baack-software/baack-ts-client`、`bun add @baack-software/baack-ts-client`

## README

这个 [鲍克](https://www.baack.co/) 提供了 TypeScript 客户端,允许使用 Baack 进行本地的打字集成 [无头CMS](https://www.baack.co/solutions/content-management) 或者说 [数字经验](https://www.baack.co/blog/2026-baack-one-year-from-cms-to-dxp) 后端 .

Baack提供数字经验,用于:

-   [内容管理](https://www.baack.co/solutions/content-management)。 。 。 .
    -   富有 [内容类型建模](https://www.baack.co/docs/concepts/content-entities) (正文,Markdown,模板,金钱,数字,日期,布尔,Lat / Long等).
    -   满 [版本历史](https://www.baack.co/docs/concepts/versions)。 。 。 .
    -   [预览草稿](https://www.baack.co/blog/editing-content-with-preview)。 。 。 .
-   [客户关系管理](https://www.baack.co/solutions/crm) API: 模拟客户和富人员工 [身份模型](https://www.baack.co/docs/reference/identity)。 。 。 .
-   [项目和任务管理](https://www.baack.co/solutions/tasks):构建内部票务或任务 [工作流程](https://www.baack.co/docs/reference/workflow) 用于满足撰写任务.
-   [社区小组和消息线索](https://www.baack.co/solutions/communities):创建有通知选择的权益组,内部工作组,或者像内容实体的未来计划那样,启动平台上任何概念的讨论线索.

## 安装

```sh
npm install @baack-software/baack-ts-client
```

该一揽子措施只针对无害环境管理,需要节点18或以后.

## 使用量

Baack客户端为管理内容和经验相关陈述提供了基线,基于 [权限](https://www.baack.co/docs/concepts/permissions) 连接平台的客户端. 要创建 API 客户端及其无记名符号, 请遵循 [从 Baack APIs 开始](https://www.baack.co/docs/guides/getting-started)。 。 。 .

```typescript
import { BaackClient, Endpoint, EntityView, type Entity } from '@baack-software/baack-ts-client';

// Configure the client with your API client's bearer token. Keep the token server-side, or use a read-only
// API client for code that runs in the browser.
const client = new BaackClient({
  baseUrl: 'https://api.baack.co',
  headers: { Authorization: `Bearer ${process.env['BAACK_API_CLIENT_TOKEN']}` },
});

// Read a page's content by path, language and variant ('' is the default variant).
const entity = await client.read<Entity>(Endpoint.ENTITY_VIEW, '/home', {
  language: 'en-GB',
  variant: '',
});

// EntityView gives name-based access to the entity's content items.
const view = EntityView.from(entity);
const title = view.text('title')?.value;
const body = view.markdown('body')?.value; // rendered HTML
```

实体查看端点走路径( 例如 `/home`)或实体URN. 大部分时间,你会使用 结合路径, `language` 财务报告和审定财务报表 `variant`。API尊重 `language` 参数,或读取器 `Accept-Language` 首选项, 这样它可以返回不同的 [语言版本](https://www.baack.co/docs/concepts/languages-variants) 从你发来的信: en-US 实体的URN来自一个更喜欢 pt-BR 的浏览器,如果存在 pt-BR 版本,你会得到该实体,与其 拥有URN. 当你发出两个, `language` 先来,然后 `Accept-Language` 偏好是倒数。 检查 `entity.language` 财务报告和审定财务报表 `entity.urn` 看看哪个版本回来了。 过 `version: 'LATEST'` 阅读最新版本, 包括 [未公布的草稿](https://www.baack.co/docs/concepts/versions),用于预览.

URN或路径是定位器,而不是该实体的承诺: `GET /v/v1/entityview/<urn-of-an-en-GB-entity>` 可以用自己的URN返回去DE实体. 返回时总是按键 `urn`。浏览器发送自己的 `Accept-Language`;一个服务器或代理读取一个只读到的符号可以代表访客转发他们的:

```typescript
const entity = await client.read<Entity>(Endpoint.ENTITY_VIEW, '/home', { variant: '' }, {
  'Accept-Language': request.headers.get('Accept-Language') ?? 'en-GB',
});
```

视图也返回 `alternativeLanguages`:返回实体的其他语言版本,在同一变体中, 页:1 `<link rel="alternate" hreflang>`。将每个地图都映射到一个URL,无论您的站点路径语言如何.

反应很浅:一个链接的对象是同一个类型,只有它的 `urn` (和 `url`) 设定,从未扩展. 一个 [实体列表](https://www.baack.co/docs/reference/entitylist) (单位:千美元)`Endpoint.ENTITY_LIST`返回每个 `entity` 这样,就读取每个实体的观点,以形成一个文本 从它自己的端点读取的项目有父项 `entity` 参考书目和实体内部 `texts` 它没有。 API( API ) 在另一个方向是允许的:将全部对象发送到需要链接的地方,并且只存储它们的URN.

`EntityView` 隐藏原始 [内容表示](https://www.baack.co/docs/reference/content-items)导航 : `view.text(name)`, (中文(简体) ), `view.markdown(name)`, (中文(简体) ), `view.image(name)` ,其他访问者则按 0 排序返回该项,或按 0 排序通过排序以达到 a 重复字段( e)`view.text('caption', 2)`,或 `view.texts('caption')` 给所有人。 我们正在找更多的帮手 astro、Next and React等框架;请通过这些问题要求具体办法.

### 错误

任何非-2xx响应都会丢出一个 `BaackApiError` 携带 HTTP `status`,原始反应 `body`, API 错误对象 (单位:千美元)`apiError`,与 `apiCode`, (中文(简体) ), `detail` 财务报告和审定财务报表 `httpCode`· ; `detail` 请求还直接提供) `method` 财务报告和审定财务报表 `url`,这样你就可以对原因作出反应,而不是分析一个消息。 注意API的答案 `404` 当请求缺乏时 它需要的会话或许可:

```typescript
import { isBaackApiError } from '@baack-software/baack-ts-client';

try {
  await client.update(Endpoint.TEXT, item.urn, item);
} catch (error) {
  if (isBaackApiError(error) && error.isUnauthorized) {
    // session expired: prompt to log in, keep the user's changes
  } else {
    throw error;
  }
}
```

网络失败( 完全没有响应) 用获取本身的错误拒绝 。 空响应机构,如 `204` 从a 删除,决定 `undefined`。 。 。 .

失败需要不同的处理,错误说:

-   **`isInvalidRequest`**(单位:千美元) `400` (或 `405`, (中文(简体) ), `413`, (中文(简体) ), `414`, (中文(简体) ), `415`, (中文(简体) ), `422`, (中文(简体) ), `431`) (中文(简体) ). 请求本身无效,而且 API通常说:例如: `{ "apiCode": "REPRESENTATION_MISSING_REQUIRED_FIELD", "detail": "updatedTimestamp" }`。 。 。 . 永久的:再次发出相同的请求 打破合同,所以行动 `apiError`更改请求, 或者告诉用户。 永远不要重试它不变.
-   **`isRefused`**: 除超时以外的任何4xx(`408`)或费率限额(`429`) (中文(简体) ). 除了无效的请求外, 这还包括 以请求以外的状态为条件的拒绝,例如过期会话(`401`或缺失的实体(`404`: 同一请求以后可能成功.
-   **`isRetryable`**: 一个5xx, `408` 或者说 `429`。在等待之后,同一请求可能会在稍后成功. `retryAfterMs` 携带 API的软件 `Retry-After`当它发送一个.

客户看守防环(`failureGuard`,默认情况下). 请求无效后,它不会发出同样的信号 再次请求5分钟。 在任何其他失败( 另4xx, 服务器出错、 超时、 速率限制或网络)后 失败)等待一秒,再翻一番可达一分一秒,随机多出一分之五,如果API `Retry-After` 这么说的 在此之前,重复一次以同样的错误一次失败,没有请求,错误的 `heldUntil` 说何时再寄 同一请求意味着相同的方法、URL、正文和每个请求 头;总是发出不同的请求,成功清除了记录. 上传没有监控 给它 `failureGuard: { refusedHoldMs, backoffMs, maxBackoffMs }`,或将其关闭 `failureGuard: false`一个打电话的人 在自己的日程安排上重复(例如一个建筑阅读器骑出一个短暂的出道时间),应该关闭,或者重复 在等待中一次失败.

### 使用 Baack 会话的浏览器

依赖用户 Baack 会话需要的浏览器客户端 `credentials: 'include'`数字 :

```typescript
const client = new BaackClient({ baseUrl: 'https://api.baack.co', credentials: 'include' });
```

`client.upload(endpoint, formData)` 发布多部分格式,例如图像文件.

`client.submitForm(endpoint, fields)` 贴出一个 urlencoded 格式 (`URLSearchParams`),如账户设置表 (单位:千美元)`Endpoint.ACCOUNT_SETUP`),并阅读了JSON的答复.

### 网络呼号

`verifyWebhook` 检查a [网点](https://www.baack.co/docs/guides/webhooks-getting-started) 交货来自 鲍克 (在JSON解析前)准确通过接收的遗体、请求头和订阅者的秘密; 添加 `bearer` 也要求您的 Webhook API 客户端的无记名符号 :

```typescript
import { verifyWebhook, WebhookVerificationError } from '@baack-software/baack-ts-client';

try {
  const delivery = await verifyWebhook({ body: await request.text(), headers: request.headers, secret, bearer });
  // delivery.trigger.event is CREATE, UPDATE or DELETE; delivery.v1 links the record that changed.
} catch (error) {
  if (error instanceof WebhookVerificationError) return new Response(null, { status: 401 });
  throw error;
}
```

`createWebhookBearerToken(client, apiClient, expires)` 创造出那个无记名标志。 带着你的底点的秘密: 它被显示一次.

## 反馈

我们欢迎反馈,请在 GitHub 中创建专题请求和问题,以方便跟踪.

## 常见问题

### @baack-software/baack-ts-client 是什么？

Baack\.co 无头 CMS 的官方TypeScript客户端

### 如何安装 @baack-software/baack-ts-client？

在项目目录运行 npm install @baack-software/baack-ts-client，或使用 pnpm add / yarn add / bun add。

### @baack-software/baack-ts-client 支持 TypeScript 吗？

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

### @baack-software/baack-ts-client 支持 ESM 还是 CommonJS？

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

### @baack-software/baack-ts-client 需要什么版本的 Node\.js？

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

### @baack-software/baack-ts-client 可以商用吗？

@baack-software/baack-ts-client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @baack-software/baack-ts-client 的下载量有多少？

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

### @baack-software/baack-ts-client 还在维护吗？

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