这个 鲍克 提供了 TypeScript 客户端,允许使用 Baack 进行本地的打字集成 无头CMS 或者说 数字经验 后端 .
Baack提供数字经验,用于:
- 内容管理。 。 。 .
- 客户关系管理 API: 模拟客户和富人员工 身份模型。 。 。 .
- 项目和任务管理:构建内部票务或任务 工作流程 用于满足撰写任务.
- 社区小组和消息线索:创建有通知选择的权益组,内部工作组,或者像内容实体的未来计划那样,启动平台上任何概念的讨论线索.
安装
npm install @baack-software/baack-ts-client
该一揽子措施只针对无害环境管理,需要节点18或以后.
使用量
Baack客户端为管理内容和经验相关陈述提供了基线,基于 权限 连接平台的客户端. 要创建 API 客户端及其无记名符号, 请遵循 从 Baack APIs 开始。 。 。 .
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 首选项, 这样它可以返回不同的 语言版本 从你发来的信:
en-US 实体的URN来自一个更喜欢 pt-BR 的浏览器,如果存在 pt-BR 版本,你会得到该实体,与其
拥有URN. 当你发出两个, language 先来,然后 Accept-Language 偏好是倒数。 检查
entity.language 财务报告和审定财务报表 entity.urn 看看哪个版本回来了。 过 version: 'LATEST' 阅读最新版本,
包括 未公布的草稿,用于预览.
URN或路径是定位器,而不是该实体的承诺: GET /v/v1/entityview/<urn-of-an-en-GB-entity>
可以用自己的URN返回去DE实体. 返回时总是按键 urn。浏览器发送自己的
Accept-Language;一个服务器或代理读取一个只读到的符号可以代表访客转发他们的:
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) 设定,从未扩展. 一个
实体列表 (单位:千美元)Endpoint.ENTITY_LIST返回每个 entity 这样,就读取每个实体的观点,以形成一个文本
从它自己的端点读取的项目有父项 entity 参考书目和实体内部 texts 它没有。 API( API )
在另一个方向是允许的:将全部对象发送到需要链接的地方,并且只存储它们的URN.
EntityView 隐藏原始 内容表示导航 : 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 当请求缺乏时
它需要的会话或许可:
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'数字 :
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 网点 交货来自
鲍克 (在JSON解析前)准确通过接收的遗体、请求头和订阅者的秘密;
添加 bearer 也要求您的 Webhook API 客户端的无记名符号 :
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 中创建专题请求和问题,以方便跟踪.