蓝比利维希 SAPI 节点.js SDK

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

所需资源

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

安装

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

快速启动

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令牌认证. 你需要一个 代号 财务报告和审定财务报表 共享机密 从你的蓝比利维格 出版设置.

// 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业务:

媒体剪贴板

// 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

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

// 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上传单通和多段流线.

// 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}%`);
}

缩略图

// 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 对象 :

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 错误的打出例外 :

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

配置

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

发展

# Install dependencies
npm install

# Type check
npm run typecheck

# Run tests
npm test

# Build
npm run build