# @bluebillywig/bb-sapi-node-sdk 中文文档

规范地址：https://npmcn.com/package/%40bluebillywig/bb-sapi-node-sdk/

版本：1\.1\.1
npm 元数据更新时间：2026-10-27T08:34:10.690Z
中文译文更新时间：2026-11-08T08:20:14.047Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：156 kB，159 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-03-20T10:58:09.921Z
- 最新版本发布：2026-10-27T08:34:10.170Z
- 近 30 天下载量：2175（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

用于节点的 Blue Billywig 服务器 API SDK

## 安装

```sh
npm install @bluebillywig/bb-sapi-node-sdk
```

也可以使用：`pnpm add @bluebillywig/bb-sapi-node-sdk`、`yarn add @bluebillywig/bb-sapi-node-sdk`、`bun add @bluebillywig/bb-sapi-node-sdk`

## README

# 蓝比利维希 SAPI 节点.js SDK

这个Node.js SDK提供了与蓝比利维格服务器API交互的抽象.

## 所需资源

-   节点.js 18
-   零运行时间依赖关系

## 安装

```bash
npm install @bluebillywig/bb-sapi-node-sdk
```

## 快速启动

```typescript
import { Sdk } from '@bluebillywig/bb-sapi-node-sdk';

const sdk = Sdk.withRPCTokenAuthentication(
  'my-publication',
  1,              // token ID
  'shared-secret' // shared secret
);

// List media clips
const response = await sdk.mediaclip.list();
const data = response.json();
console.log(data);
```

## 认证

SDK使用基于HOTP的RPC令牌认证. 你需要一个 **代号** 财务报告和审定财务报表 **共享机密** 从你的蓝比利维格 出版设置.

```typescript
// Recommended: use the convenience factory
const sdk = Sdk.withRPCTokenAuthentication('my-publication', tokenId, sharedSecret);

// Or provide a custom authenticator
import { Sdk, RPCTokenAuthenticator } from '@bluebillywig/bb-sapi-node-sdk';

const authenticator = new RPCTokenAuthenticator(tokenId, sharedSecret);
const sdk = new Sdk('my-publication', authenticator);
```

**时钟同步**: RPC 代号为时间(HOTP). 客户端和服务器时钟都必须合理同步(在符号到期窗口内,默认为120秒). 重大的时钟漂移会导致认证失败.

## 实体

所有实体都酌情支持标准CRUD业务:

| 实体 | 列表 | 获取 | 创建 | 更新 | 删除 |
| --- | --- | --- | --- | --- | --- |
| `sdk.mediaclip` | 对 | 对 | 对 | 对 | 对 |
| `sdk.playlist` | 对 | 对 | 对 | 对 | 对 |
| `sdk.channel` | 对 | 对 | 对 | 对 | 对 |
| `sdk.playout` | 对 | 对 | 对 | 对 | 对 |
| `sdk.subtitle` | 对 | 对 | 对 | 对 | 对 |
| `sdk.thumbnail` | \- 说吧 | \- 说吧 | \- 说吧 | \- 说吧 | \- 说吧 |

### 媒体剪贴板

```typescript
// List
const response = await sdk.mediaclip.list(15, 0, 'createddate desc');

// Get (with optional language and job inclusion)
const response = await sdk.mediaclip.get(123);
const response = await sdk.mediaclip.get(123, 'en', false);

// Create
const response = await sdk.mediaclip.create({ title: 'My Video' });

// Update
const response = await sdk.mediaclip.update(123, { title: 'Updated Title' });

// Delete (with optional purge)
const response = await sdk.mediaclip.delete(123);
const response = await sdk.mediaclip.delete(123, true); // purge
```

### 播放列表、 频道、 播放、 字幕

```typescript
// All follow the same pattern
const response = await sdk.playlist.list();
const response = await sdk.playlist.get(1);
const response = await sdk.playlist.create({ title: 'My Playlist' });
const response = await sdk.playlist.update(1, { title: 'Updated' });
const response = await sdk.playlist.delete(1);
```

## 文件上传

SDK支持通过预先签名的URL向S3上传单通和多段流线.

```typescript
// 1. Initialize the upload
const initResponse = await sdk.mediaclip.initializeUpload('/path/to/video.mp4');
initResponse.assertOk();
const uploadData = initResponse.json();

// 2. Execute the upload (streams file data, no full-file buffering)
const success = await sdk.mediaclip.executeUpload('/path/to/video.mp4', uploadData);

// 3. (Optional) Track upload progress
for await (const progress of sdk.mediaclip.uploadProgressGenerator(
  uploadData.listPartsUrl,
  uploadData.headObjectUrl,
  uploadData.chunks,
)) {
  console.log(`Upload progress: ${progress}%`);
}
```

## 缩略图

```typescript
// Generate an absolute thumbnail URL with dimensions
const url = sdk.thumbnail.getAbsoluteImagePath('/path/to/image.jpg', 640, 360);
// => https://my-publication.bbvms.com/image/640/360/path/to/image.jpg
```

## 反应处理

所有实体方法返回a `SapiResponse` 对象 :

```typescript
const response = await sdk.mediaclip.get(123);

// Check status
if (response.ok) {
  const data = response.json();
}

// Or assert (throws on non-2xx)
response.assertOk();
const data = response.json();

// Access response details
response.statusCode;           // e.g. 200
response.body;                 // raw body string
response.header('Content-Type');
response.queryParam('limit');  // query param from the request URL
response.statusCategory;       // HTTPStatusCodeCategory enum

// Batch response utilities
SapiResponse.allOk(responses);         // true if all 2xx
SapiResponse.assertAllOk(responses);   // throws on first non-2xx
SapiResponse.failedResponses(responses); // generator yielding non-2xx responses
```

## 处理错误

SDK 投放 HTTP 错误的打出例外 :

```typescript
import {
  HTTPRequestException,
  HTTPClientErrorException,
  HTTPServerErrorException,
} from '@bluebillywig/bb-sapi-node-sdk';

try {
  const response = await sdk.mediaclip.get(999);
  response.assertOk();
} catch (error) {
  if (error instanceof HTTPClientErrorException) {
    // 4xx error
    console.error(`Client error ${error.statusCode}: ${error.message}`);
    console.error('Response body:', error.responseBody);
  } else if (error instanceof HTTPServerErrorException) {
    // 5xx error
    console.error(`Server error ${error.statusCode}: ${error.message}`);
  }
}
```

## 配置

```typescript
const sdk = Sdk.withRPCTokenAuthentication('my-publication', tokenId, sharedSecret, {
  // Override the base URI (useful for testing or custom deployments)
  baseUri: 'https://custom-host.example.com',

  // Inject a custom fetch implementation (useful for testing)
  fetch: customFetchFn,
});
```

## 发展

```bash
# Install dependencies
npm install

# Type check
npm run typecheck

# Run tests
npm test

# Build
npm run build
```

## 常见问题

### @bluebillywig/bb-sapi-node-sdk 是什么？

用于节点的 Blue Billywig 服务器 API SDK

### 如何安装 @bluebillywig/bb-sapi-node-sdk？

在项目目录运行 npm install @bluebillywig/bb-sapi-node-sdk，或使用 pnpm add / yarn add / bun add。

### @bluebillywig/bb-sapi-node-sdk 支持 TypeScript 吗？

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

### @bluebillywig/bb-sapi-node-sdk 支持 ESM 还是 CommonJS？

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

### @bluebillywig/bb-sapi-node-sdk 需要什么版本的 Node\.js？

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

### @bluebillywig/bb-sapi-node-sdk 可以商用吗？

@bluebillywig/bb-sapi-node-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bluebillywig/bb-sapi-node-sdk 的下载量有多少？

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

### @bluebillywig/bb-sapi-node-sdk 还在维护吗？

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