# @bikefinder/api-client 中文文档

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

版本：2\.0\.0
npm 元数据更新时间：2026-11-06T16:04:13.181Z
中文译文更新时间：2026-11-08T02:16:46.673Z
软件包许可：UNLICENSED

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

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

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：4.5 MB，57 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：2 个
- 首次发布：2026-10-22T21:48:59.608Z
- 最新版本发布：2026-11-06T11:58:11.567Z
- 近 30 天下载量：8690（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

为 BikeFinder api 创建了 REST 和 SignalR 客户端.

## 安装

```sh
npm install @bikefinder/api-client
```

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

## README

# @bikefinder/ api-客户端

生成 REST 和 SignalR 客户端 [API 服务](https://npmcn.com/package/services/api/README.md). Hey API 从 OpenAPI 生成命名为 HTTP 的方法,类型和 Zod 验证. 已打入信号R. 客户端. TypeScript 从服务器执行的 C# 接口生成中枢代理. 官员 `@microsoft/signalr` 客户端拥有流和连接管理. 版本 1 是从以前的窄端 SDK; 旧的 `/admin` 财务报告和审定财务报表 `/v1` 软件包条目被删除.

```ts
import { createBikeFinderClient } from "@bikefinder/api-client";

const api = createBikeFinderClient({
  baseUrl: "https://api.example.com",
  getToken: () => auth0.getAccessTokenSilently(),
});

const result = await api.requests.getTracker({ path: { id: trackerId } });
if (result.error) showProblem(result.error);
else render(result.data.data);

await api.realtime.connection.start();
const subscription = api.realtime.hub.watchTracker(trackerId).subscribe({
  next: (document) => render(document.data),
  error: (error) => showSubscriptionError(error),
  complete: () => showSubscriptionEnded(),
});

// Cancel this native SignalR stream and its server-side Firestore listener.
subscription.dispose();
// On sign-out/account change, discard account data and dispose this client.
await api.dispose();
```

使用 `staffRealtime.connection` 财务报告和审定财务报表 `staffRealtime.hub` 工作人员业务。 连接不开始创建; 只启动应用程序所用的连接 。 页面流接受一个查询对象, 例如 `api.realtime.hub.watchTrackers({limit: 50})`。通过返回 `nextCursor` 作为 `cursor` 用于另一页.

该应用程序拥有订阅共享,保留数据和账户范围. 订阅本地 `connection.onreconnecting`, (中文(简体) ), `onreconnected` 财务报告和审定财务报表 `onclose` 用于更新UI的事件。 每个连接上都配置了自动再连接,但不重试初始 `start()` 失败或恢复流引用:在重新连接后再创建订阅. 终止的流已完成 。 没有自定义的监视状态或订阅协调器 .

应用程序的 Auth0 SDK 提供符和手柄刷新. 为新的账户会话创建新客户端 . `dispose()` 中止 HTTP 请求并停止两个连接 。 请求使用无记名认证,省略 cookie并拒绝重定向. 网络/ 验证失败拒绝; HTTP 问题细节作为 `result.error` 默认。 写字永远不会自动重试; a `503 operation_unconfirmed` 可能已经承诺了.

REST响应使用生成了Zod验证. 流值生成了静态类型并使用本地信号R解码器;用于运行时间验证,导入 `zTrackerDocument` 从 `@bikefinder/api-client/schemas` 打电话 `.parse(value)`两种运输都提到相同的有效载荷类型。 Firestore 响应来自 C# DTO 中的实际 `Firestore/TrackerData.cs` 财务报告和审定财务报表 `Firestore/ResourceData.cs`。API在回复前转换所储存的数据; `readIssues` 识别无法使用的存储字段。 额外的元数据仍然存在于明确的JSON扩展字段中. 服务器序列化响应固定装置通过API和生成客户端测试验证. 身份证就是Firestore身份证.

其他土著资源通过特定资源文件类型暴露其已知领域。 他们的C#合同只暴露了被解释的字段;无关的被储存的字段留在API内. 跟踪报告和统计有具体的模型,访问码存储从回复中省略. 观测值产生结合: `observation.definitionId === 5`, (中文(简体) ), `observation.value.percent` 是一个数字。 当前读取显示同一歧视者; 检查 `observationId !== null` 在使用本读数之前。 设备设置,内置的工作流程描述符和命令参数tuple都是由Cononical协议JSON合同产生的. 自行车和首选补丁暴露了所支持的属性并区分了遗漏和明示的无效. 响应验证器在检查已知值、所需属性和enum时保留了额外的API字段。 请求模型保留其已声明的限制,被关闭的对象拒绝未知的写字字段. 共享的有效载荷产生了读取的变体,因此宽容的反应绝不会削弱请求计划.

手写入口只配置客户端,认证和处理. 生成了枢纽方法,线名和流式签名. 所生成的只类型桥重用OpenAPI有效载荷定义,而不是发布第二套模型. 没有RxJS或MQTT依赖.

AWS的工作人员方法涉及一般观察,指挥和设置资源. 使用 `requests.readAwsObservations` 选择当前观测系列, `getAwsSettings` 读取单子设置阴影,以及 `updateAwsSettings` 以预期版本补丁输入的设置。 生成的 `staffRealtime.hub.watchAwsObservations`, (中文(简体) ), `watchAwsCommand` 财务报告和审定财务报表 `watchAwsSettings` 方法返回本地信号流。 见 [AWS 资源映射](https://npmcn.com/package/docs/api/aws.md) 用于数据库和命令接受语义.

运行时间需要标准的获取、请求、 Blob、 中止控制器和 `AbortSignal.any`编号 :`throwIfAborted`,加由 SignalR 支持的 WebSocket 执行。 在需要时创建客户端之前,先提供相关的平台多填充.

## 改造和建造

这个 [协议所有权指南](https://npmcn.com/package/protocol/README.md) 识别来源 每个合同和上游生成步骤。 编辑这些来源之前 重新生成这个客户端. `openapi/api.json`, (中文(简体) ), `src/generated`, (中文(简体) ), `src/signalr`, (中文(简体) ), `src/device-schema.ts` 财务报告和审定财务报表 `src/workflow-schema.ts` 产出 由客户建设和消费者.

从寄存器根 :

```powershell
dotnet tool restore
dotnet restore services/api/src/Api.csproj --locked-mode
dotnet build services/api/src/Api.csproj --no-restore
npm ci --ignore-scripts
npm run contract --workspace @bikefinder/api-client
npm run generate --workspace @bikefinder/api-client
npm run check --workspace @bikefinder/api-client
npm test --workspace @bikefinder/api-client
npm run build --workspace @bikefinder/api-client
```

被绑定的.NET工具配置于 `.config/dotnet-tools.json`. 合同导出在当地运行已建服务以获取 OpenAPI;不需要Firebase 证书或实时请求。 如果任一生成器都失败, 则生成失败 。 生成源是承诺的,必须一起再生. `tsc-alias` 在汇编无害环境管理包时解决产生的无扩展进口。 重点测试包括认证、文件忠诚、二进制写作、不确定的写作答复、本地代理引用/取消和处置.

## 发布

弹出此软件包的版本和根锁文件 . **发布 API 客户端** (单位:千美元)`publish-client.yml`当软件包显示在 `main`;也可以手工操作. 工作流程检查生成的策略, 运行 使用 GitHub OIDC 创建并发布 SDK 测试。 它没有部署AWS 服务,不需要 npm 令牌或每版浏览器批准.

Npm 软件包的可信任的出版商必须命名组织 `bikefinder`, (中文(简体) ), 仓库 `aws_cloud`工作流程 `publish-client.yml`直接 `npm publish` 允许且没有环境名称。 此账户设置在 软件包的 npm 设置。 见 [npm 信任的出版](https://docs.npmjs.com/trusted-publishers/)。 。 。 .

命令 HTTP 和信号R 方法返回 `AwsCommand`请求、中介出版物和 `execution.accepted`编号 :`execution.completed` 这些是资源中独特的阶段。 客户端不再加入命令-结果观测或暴露出单独的结果端点. 完成部分包括一个输入的响应数据联盟和经认证的接收时间.

## 观察时间戳

观测历史和当前阅读 `measuredAt` 财务报告和审定财务报表 `receivedAt`。 。 。 . 观察ID是不透明的服务器生成的引用. 他们没有靴子或 序列信息。 不同的行可以有相同的捕获时间戳; 客户不得推断其身份证上的人身订单。 历史可以包含 单独一行,用于同一读数的一次发送.

源合同在SDK 1.0.14后有所改变. 在部署消费者之前, 发布下一次 SDK 发布并更新其注册依赖和锁定文件. 本地验证可以使用新建的 SDK; 保留该临时覆盖 承诺的消费者依赖.

设置响应使用 API 拥有 `AwsSettingsSnapshot` hTTP 和信号: 已读 `desired`, (中文(简体) ), `reported`, (中文(简体) ), `application`、能力和计划/版本证据. `readIssues` 识别无法解释的 API 存储值。 该资源不会暴露潜在的AWS阴影文档或其独立所有者. 设置字段和界限来自与固件相同的协议注册.

指挥部读取验证所储存的身份、目录论据、文物和执行证据。 错误的单命令读取返回 `command_unreadable`; 命令页面保存有效项目并附加请求 `readIssues`。两个命令流都发出 `AwsCommandUpdate` 或经过验证 `command` 或一个 `readIssue`,允许随后的事件继续下去.

## 支持的API消费者

SDK 2.0.0是明确批准的发射前模式之后的支持基线 对齐。 代替实验 `powerSaving`编号 :`precision` 模式名称和 它们的时间设置名称使用 `standard`编号 :`security`更早的客户需要 这些AWS资源一次性升级. 采取的宽容应对政策 在1.0.27中保留。 模式可用性是一个 ID 列表, 和选中的模式 ID 是对每个跟踪器的云目录进行验证的打开字符串。 添加或删除 目录选择不需要再发布 SDK .

API CI 安装所选择的最古老支持的不可移动 npm 释放 `tools/check-api-compatibility.mjs`。它验证新服务器序列化 使用已出版的读取器的防火炉、指令和设置装置 其HTTP变压器和流电源计划,并检查信封中的添加 和筑巢水平。 软件包包括它出口的 OpenAPI 合同 下级 `@bikefinder/api-client/openapi` 为了比较.

这个 `compatibility` 职务与公布的合同相对应 对这两份文件都采取同样的宽容政策。 请求验证必须严格. 门拒绝删除的端点或响应字段、不兼容类型和 界限、新需要的输入和互不相容的符号更改。 添加单独的 API 用于打破更改并保留所支持的 v1 路由的版本。 提高 最古老的支持SDK版本是明确的退休决定,而不是例行公事 通过CI的方式。 开发部署和生产促进都需要这项工作.

运行时验证仍然拒绝错误的已知数据. 申请应予保留 最后一个有效的流消息,并隔离每个资源的失败。 补丁时 设置, 只发送已更改的支持字段; 保存不熟悉的响应字段 并且不将完整答复复制到书面有效载荷中.

## 常见问题

### @bikefinder/api-client 是什么？

为 BikeFinder api 创建了 REST 和 SignalR 客户端\.注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @bikefinder/api-client？

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

### @bikefinder/api-client 支持 TypeScript 吗？

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

### @bikefinder/api-client 支持 ESM 还是 CommonJS？

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

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

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

### @bikefinder/api-client 可以商用吗？

@bikefinder/api-client 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bikefinder/api-client 的下载量有多少？

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

### @bikefinder/api-client 还在维护吗？

最新版本 2\.0\.0 发布于 2026/11/06（1 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 47 个；首次发布于 2026/10/23。作者已将其标记为弃用，新项目建议寻找替代方案。