# @blacktopdata/blacktop-api-client 中文文档

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

版本：0\.1\.81
npm 元数据更新时间：2026-10-31T14:39:59.569Z
中文译文更新时间：2026-10-31T16:32:05.278Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2 MB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-30T20:17:14.843Z
- 最新版本发布：2026-10-31T14:39:59.419Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

用于blacktop-api (ocblacktop) v1端点的类型TypeScript客户端。由OpenAPI生成。

## 安装

```sh
npm install @blacktopdata/blacktop-api-client
```

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

## README

# @blacktopdata / blacktop-api-client

的类型化TypeScript客户端 **blacktop-api** （ocblacktop） v1端点。生成自API的OpenAPI规范-不手动编辑 `src/`.

## 安装

```sh
npm install @blacktopdata/blacktop-api-client
```

获取API密钥 [https://ocblacktop.com/api](https://ocblacktop.com/api)。Python用户: `pip install blacktop-data`.

## 使用

```ts
import { client, EventsService } from '@blacktopdata/blacktop-api-client';

client.setConfig({
  baseUrl: 'https://api.ocblacktop.com',
  headers: { 'X-API-Key': process.env.BLACKTOP_API_KEY! },
});

const { data, error } = await EventsService.listF1Events({
  query: { page: 1, limit: 20 },
});
```

赛道系列（F1、NASCAR、IndyCar、MotoGP）共享资源导向服务 （`DriversService`， `EventsService`， `SeasonsService`， `StandingsService`,……)。这个 **世界拉力锦标赛** 是拉力型的，有自己的服务- `WrcRalliesService`， `WrcStandingsService`， `WrcSeasonsService`, `WrcDriversService`：

```ts
import { client, WrcRalliesService, WrcStandingsService } from '@blacktopdata/blacktop-api-client';

// A season's rallies
const { data: rallies } = await WrcRalliesService.listWrcRallies({
  query: { year: 2024 },
});

// Stage results for a rally (driver + co-driver, stage times, gaps)
const { data: stage } = await WrcRalliesService.getWrcRallyStage({
  path: { id: rallyId, stageId },
});

// Drivers' championship standings
const { data: standings } = await WrcStandingsService.getWrcDriverStandings({
  query: { year: 2024 },
});
```

> 服务和方法名是由OpenAPI规范生成的；重新生成SDK （见下），以便在任何API更改后拾取新的端点。

## 版本控制

-   **主要的** 破坏合同的改动（移除字段，改变类型，移除端点）
-   **小** 附加的改动（新的端点，新的可选字段）
-   **补丁** - docs / nonfunctional

由CI自动碰撞；销, `^X.Y.Z` 自动接收minor + patch。

## 本地再生

```sh
# from blacktop-api repo root
npm run generate:docs        # writes openapi.json
npm run --prefix packages/sdk generate
npm run --prefix packages/sdk build
```

## 常见问题

### @blacktopdata/blacktop-api-client 是什么？

用于blacktop-api \(ocblacktop\) v1端点的类型TypeScript客户端。由OpenAPI生成。

### 如何安装 @blacktopdata/blacktop-api-client？

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

### @blacktopdata/blacktop-api-client 支持 TypeScript 吗？

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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