@enerlab/thingsboard-client

Type-safe TypeScript client for the ThingsBoard REST API with Zod v4 runtime validation.

Generated from the official ThingsBoard OpenAPI 3.1 spec using @hey-api/openapi-ts.

Features

• Full ThingsBoard Community Edition REST API coverage
• login() / logout() helpers (not in the OpenAPI spec, provided manually)
• TypeScript types for all endpoints, request bodies, and responses
• Zod schemas for runtime validation at API boundaries
• Native fetch — works in Node.js 20+, Bun, Deno, and browsers
• Tree-shakeable — import only the endpoints you use for minimal bundle size

Installation

pnpm add @enerlab/thingsboard-client

Quick Start

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('[email protected]', '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)
}

Using an Existing Token

If you already have a JWT (e.g. from a previous session), set it directly:

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' },
})

Using a Separate Client Instance

For multiple ThingsBoard instances or isolated auth contexts, create a dedicated client:

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

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

await login('[email protected]', 'admin', { client: myClient })

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

Tree-Shaking

All SDK functions are exported as standalone, tree-shakeable functions. Your bundler will only include the endpoints you actually import, keeping your bundle small — especially important for frontend and mobile apps.

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

Zod Schemas

Import Zod schemas for runtime validation:

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)
}

Development

Prerequisites

• Node.js 20+
• pnpm 8+

Setup

# Install dependencies
pnpm install

# Download the ThingsBoard OpenAPI spec
# Defaults to https://demo.thingsboard.io — override with THINGSBOARD_SPEC_URL
pnpm fetch-spec

# Generate the TypeScript client
pnpm generate

# Type-check
pnpm typecheck

# Run tests
pnpm test

# Lint
pnpm lint

# Build
pnpm build

Updating the Spec

To update to a newer ThingsBoard API version:

# 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

Project Structure

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 Reference

The full API documentation is available at:

• ThingsBoard REST API Docs
• Interactive Swagger UI (demo instance)

License

MIT