# @enerlab/thingsboard-client 中文文档

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

版本：4\.3\.1-pe\.1\.5
npm 元数据更新时间：2026-10-23T19:45:33.211Z
中文译文更新时间：2026-11-13T17:29:33.575Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：22.9 MB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-03-03T15:31:30.499Z
- 最新版本发布：2026-10-23T19:45:32.761Z
- 近 30 天下载量：3876（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

使用 Zod v4 运行时间验证的 TypsBoard REST API 的 Type 安全 TypeScript 客户端

## 安装

```sh
npm install @enerlab/thingsboard-client
```

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

## README

# @enerlab/thingsboard-客户端

类型安全 Script 客户端 [企业](https://thingsboard.io/) (原始内容存档于2018-03-26) (英语). REST API with [佐德语Name](https://zod.dev/) v4 运行时验证.

来源于官方 ThingsBoard OpenAPI 3.1 spec 使用 [@ hey- api/ openapi- ts (韩语)](https://heyapi.dev/)。 。 。 .

## 特征

-   Full ThingsBoard REST API覆盖率,由 TB 专业版 spec生成(PE 是 CE 的超级集——只使用 CE 的消费者会看到 SDK 函数,用于 PE 唯一的端点,即他们的服务器上的404)
-   `login()` 编号 : `logout()` 助手( 不在 OpenAPI 类别中, 手工提供)
-   用于所有端点、请求正文和响应的脚本类型
-   在 API 边界进行运行时间验证的 Zod 计划
-   土著 `fetch` – 在Node.js 20+, Bun, Deno 和浏览器中工作
-   可树摇动 — 只导入最小捆绑大小的端点

## 版本

软件包版本映射了目标ThingsBoard服务器版本,外加一个预放标签,将精确的上游光谱构建:

```
MAJOR.MINOR.PATCH-<edition>.<build>.<client-revision>
```

-   **`MAJOR.MINOR.PATCH`** 与 TB 服务器版本完全匹配(例如:. `4.3.1`) (中文(简体) ).
-   **`<edition>`** 光谱来源于 TB 版本 : `pe` 或者说 `ce`。 。 。 .
-   **`<build>`** 是TB的积分计数器 `info.version` (例如:. `4.3.1.1PE` → `1`) (中文(简体) ).
-   **`<client-revision>`** 仅针对客户端修改的递增(codegen tweaks,补丁-script 更新,帮助者添加),对应相同的上层光谱构建. 开始于 `0` 每个新光谱获取 .

简单的版本像 `4.3.1` 为: **从未出版** ——每一次放出都带有完整的放出前标记,因此上游出处总是可见. 消费者使用 `^4.3.1` (c) 明确标出:

```jsonc
"@enerlab/thingsboard-client": "4.3.1-pe.1.0"
```

| 活动 | 版本 |
| --- | --- |
| 从 TB 创建的第一个客户端 `4.3.1.1PE` | `4.3.1-pe.1.0` |
| 只有客户端的固定; 相同的光谱构建 | `4.3.1-pe.1.1` |
| 对抗肺结核 `4.3.1.2PE` | `4.3.1-pe.2.0` |
| 4.3.2 (建造0,PE) | `4.3.2-pe.0.0` |

### 支持的 TB 版本/ 分支布局

`main` 跟踪最新的TB小于包目标。 当套件移动到一个新的肺结核未成年人时, a `release/<MAJOR>.<MINOR>.x` 树枝断了 `main` 首先; 仅客户端的修补可以返回到该分支上并作为新版本发布 `-N` 对旧行的修订。 目前仅 `main` 它的目标是TB 4.3.x.

## 安装

```bash
pnpm add @enerlab/thingsboard-client
```

## 快速启动

```ts
import { client, login, getDeviceByIdUsingGet } from '@enerlab/thingsboard-client'

// Configure the base URL
client.setConfig({
  baseUrl: 'https://your-thingsboard.com',
})

// Login — auto-stores the JWT token on the client
await login('tenant@thingsboard.org', 'tenant')

// Make type-safe API calls
const { data, error } = await getDeviceByIdUsingGet({
  path: { deviceId: 'your-device-id' },
})

if (error) {
  console.error('Failed to fetch device:', error)
} else {
  console.log('Device:', data.name)
}
```

### 使用已存在的托肯

如果您已经有一个JWT(例如上一个会话),请直接设定:

```ts
import { client, getDeviceByIdUsingGet } from '@enerlab/thingsboard-client'

client.setConfig({
  baseUrl: 'https://your-thingsboard.com',
  auth: 'eyJ...',
})

const { data } = await getDeviceByIdUsingGet({
  path: { deviceId: 'your-device-id' },
})
```

### 使用单独的客户端实例

对于多个TimesBoard实例或孤立的认证上下文,创建专用客户端:

```ts
import { createClient, createConfig, login, getDeviceByIdUsingGet } from '@enerlab/thingsboard-client'

const myClient = createClient(createConfig({
  baseUrl: 'https://other-thingsboard.com',
}))

await login('admin@thingsboard.org', 'admin', { client: myClient })

const { data } = await getDeviceByIdUsingGet({
  path: { deviceId: 'device-id' },
  client: myClient,
})
```

## 树摇

所有 SDK 函数都导出为独立的可树动函数. 您的捆绑机将只包含您实际导入的端点, 保持您的捆绑小—— 对前端和移动应用程序尤其重要 .

```ts
// Only getDeviceByIdUsingGet and its Zod validator end up in your bundle
import { getDeviceByIdUsingGet } from '@enerlab/thingsboard-client'
```

## 佐德·斯克马斯

导入 Zod 计划用于运行时间验证 :

```ts
import { zDevice } from '@enerlab/thingsboard-client/zod'

// Validate external data
const result = zDevice.safeParse(unknownData)
if (result.success) {
  console.log('Valid device:', result.data.name)
}
```

## 发展

### 先决条件

-   节点.js 20+
-   pnpm 8+ 时间长度

### 设置

```bash
# Install dependencies
pnpm install

# Download the ThingsBoard OpenAPI spec
# Default URL is https://demo.thingsboard.io (Community Edition).
# Override with THINGSBOARD_SPEC_URL to target a PE instance or a specific TB version.
pnpm fetch-spec

# Generate the TypeScript client
pnpm generate

# Type-check
pnpm typecheck

# Run tests
pnpm test

# Lint
pnpm lint

# Build
pnpm build
```

### 更新光谱

要更新到更新的 ThingsBoard API 版本 :

```bash
# From demo.thingsboard.io (latest Community Edition)
pnpm fetch-spec

# Or from your own instance
THINGSBOARD_SPEC_URL=https://my-tb.example.com/v3/api-docs?group=thingsboard pnpm fetch-spec

# Regenerate the client
pnpm generate
```

### 项目结构

```
thingsboard-client/
├── src/
│   ├── index.ts              # Package entry — re-exports everything
│   ├── auth.ts               # login() / logout() helpers
│   └── generated/            # Auto-generated by @hey-api/openapi-ts (gitignored)
│       ├── client.gen.ts     # Fetch client instance
│       ├── sdk.gen.ts        # SDK functions for every endpoint
│       ├── types.gen.ts      # TypeScript types
│       └── zod.gen.ts        # Zod schemas
├── tests/
│   ├── auth.test.ts          # login/logout tests
│   └── zod-contracts.test.ts # Zod schema contract tests
├── spec/
│   └── thingsboard-openapi.json  # Downloaded OpenAPI spec (committed)
├── scripts/
│   └── fetch-spec.ts         # Script to download the spec
├── vitest.config.ts
├── openapi-ts.config.ts      # @hey-api/openapi-ts configuration
├── tsconfig.json
└── package.json
```

## ThingsBoard API 参考文献

API文件全文见:

-   [物板 REST API 文档](https://thingsboard.io/docs/reference/rest-api/)
-   [交互式 Swagger 用户界面](https://demo.thingsboard.io/swagger-ui/index.html) (演示实例)

## 许可证

麻省理工学院

## 常见问题

### @enerlab/thingsboard-client 是什么？

使用 Zod v4 运行时间验证的 TypsBoard REST API 的 Type 安全 TypeScript 客户端

### 如何安装 @enerlab/thingsboard-client？

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

### @enerlab/thingsboard-client 支持 TypeScript 吗？

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

### @enerlab/thingsboard-client 支持 ESM 还是 CommonJS？

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

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

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

### @enerlab/thingsboard-client 可以商用吗？

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

### @enerlab/thingsboard-client 的下载量有多少？

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

### @enerlab/thingsboard-client 还在维护吗？

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