SAPI Node.js SDK

1.0 | Introduction

The SAPI Node.js SDK is an official Blue Billywig package for the Server API (SAPI). It is written in TypeScript and has zero runtime dependencies. It covers entity CRUD operations (mediaclips, playlists, channels, playouts, subtitles), streaming file uploads to S3, and thumbnail URL generation.

GitHub repository: bluebillywig/bb-sapi-node-sdk

2.0 | Requirements

• Node.js 18 or higher

3.0 | Installation

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

4.0 | Authentication

The SDK uses HOTP-based RPC token authentication. You need the token ID and shared secret from your Blue Billywig publication (see API key management).

The shared secret shown in your account settings has the format {id}-{hex_secret}, for example 490-55c491d354cfefb9b4d26cf22fbdd0a1. The number before the dash is the token ID; the hex string after the dash is the secret.

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

const sdk = Sdk.withRPCTokenAuthentication(
  'my-publication', // publication name (subdomain of bbvms.com)
  490,              // token ID (the number before the dash)
  '55c491d354...'   // shared secret (the hex string after the dash)
);

The token is time-based with a 120-second validity window. Ensure your server clock is synchronized with NTP.

5.0 | Quick start

5.1 | List mediaclips

const response = await sdk.mediaclip.list(15, 0, 'createddate desc');
const data = response.json();
console.log(data);

5.2 | Get a single mediaclip

const response = await sdk.mediaclip.get(12345);

if (response.ok) {
  const clip = response.json();
  console.log(clip.title);
}

5.3 | Create, update, and delete

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

// Update
await sdk.mediaclip.update(12345, { title: 'Updated Title' });

// Delete (soft)
await sdk.mediaclip.delete(12345);

// Delete permanently
await sdk.mediaclip.delete(12345, true); // purge = true

The same pattern applies to sdk.playlist, sdk.channel, sdk.playout, and sdk.subtitle.

5.4 | Upload a video file

The SDK streams the file to S3 directly; there is no full-file buffering in memory.

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

// 2. Execute the upload
await sdk.mediaclip.executeUpload('/path/to/video.mp4', uploadData);

6.0 | Supported entities

Thumbnail URL generation is available as a helper method:

const url = sdk.thumbnail.getAbsoluteImagePath('/path/to/image.jpg', 640, 360);
// => https://my-publication.bbvms.com/image/640/360/path/to/image.jpg

7.0 | Full documentation

The GitHub README contains the complete method reference, response handling details, error handling, and configuration options: github.com/bluebillywig/bb-sapi-node-sdk