@teradek/sdk

Official TypeScript SDK for the Teradek REST API — control Prism-series broadcast codecs programmatically.

• Full TypeScript types for every endpoint and response
• Automatic OAuth token management with transparent refresh
• Dual ESM/CJS package
• Single dependency (undici for TLS configuration)

Installation

npm install @teradek/sdk

Quick Start

import { Teradek } from "@teradek/sdk";

const device = new Teradek({
  host: "192.168.1.100",
  password: "your-admin-password",
  rejectUnauthorized: false, // self-signed cert
});

// Get device info
const info = await device.system.info();
console.log(info.settings["Device Model"]); // "Prism-855"

// Start a stream
await device.streams.start(0);

Constructor Options

const device = new Teradek({
  // Required — device IP address or hostname
  host: "192.168.1.100",

  // Authentication (one of password or accessToken is required)
  password: "admin-password",       // OAuth password grant (recommended)
  accessToken: "...",               // Existing access token
  refreshToken: "...",              // Existing refresh token (enables auto-refresh)

  // Connection
  https: true,                      // Use HTTPS (default: true). Set to false for plain HTTP.
  rejectUnauthorized: true,         // Verify TLS certificates (default: true). Set to false for self-signed certs.

  // Callbacks
  onTokenRefresh: (tokens) => {},   // Called whenever tokens are refreshed
});

Authentication

The SDK handles OAuth 2.0 automatically. Pass your device password and the SDK will obtain and refresh tokens as needed.

// Password auth (recommended) — tokens managed automatically
const device = new Teradek({
  host: "192.168.1.100",
  password: "admin-password",
  rejectUnauthorized: false,
});

// Existing tokens — useful for persisting sessions
const device = new Teradek({
  host: "192.168.1.100",
  accessToken: "rYDVtxfHdH7Igk5qdMEWMJZAJpg1Gjvy",
  refreshToken: "bNLzvBOEqwDNYApV9jduhjlVXIoOp9kB",
  rejectUnauthorized: false,
});

// Persist tokens when they refresh
const device = new Teradek({
  host: "192.168.1.100",
  password: "admin-password",
  rejectUnauthorized: false,
  onTokenRefresh: (tokens) => {
    saveToDatabase(tokens.access_token, tokens.refresh_token);
  },
});

You can also manage authentication manually:

// Explicitly authenticate (usually not needed — happens automatically on first request)
const tokens = await device.authenticate();

// Manually refresh the access token
const newTokens = await device.refreshToken();

TLS / Self-Signed Certificates

Prism devices use self-signed TLS certificates by default. Disable verification for local network access:

const device = new Teradek({
  host: "192.168.1.100",
  password: "admin-password",
  rejectUnauthorized: false,
});

HTTP (Plain)

If your device has HTTP enabled and you want to skip TLS entirely:

const device = new Teradek({
  host: "192.168.1.100",
  password: "admin-password",
  https: false,
});

API Reference

System

await device.system.info();
await device.system.firmware.check();
await device.system.firmware.getSettings();
await device.system.firmware.updateSettings({ auto_check: false });
await device.system.firmware.upgrade(); // Caution: triggers a firmware upgrade and device reboot

Encoders

await device.encoders.info();

// Video
await device.encoders.video.getSettings();
await device.encoders.video.updateSettings({ codec: "hevc", bitrate_list: 15000 });

// Audio
await device.encoders.audio.getSettings();
await device.encoders.audio.updateSettings({ bitrate_list: 256000 });

// Metadata / SCTE
await device.encoders.metadata.getSettings();
await device.encoders.metadata.updateSettings({ "closed-captions": true });
await device.encoders.metadata.insertScte();

// Recording
await device.encoders.record.getSettings();
await device.encoders.record.updateSettings({ format: "mov" });
await device.encoders.record.info();
await device.encoders.record.start();
await device.encoders.record.stop();

// Snapshot
const jpeg = await device.encoders.snapshot(); // ArrayBuffer

Decoders

await device.decoders.info();

// Video ingest
await device.decoders.video.getMode();
await device.decoders.video.setMode("SRT");
await device.decoders.video.getSettings();
await device.decoders.video.updateSettings({ /* mode-specific settings */ });

// Audio output
await device.decoders.audio.getSettings();
await device.decoders.audio.updateSettings({ /* ... */ });
await device.decoders.audio.channel(0).getSettings(); // per-channel (0–15)

// Metadata
await device.decoders.metadata.getSettings();
await device.decoders.metadata.updateSettings({ /* ... */ });

// Recording
await device.decoders.record.getSettings();
await device.decoders.record.updateSettings({ format: "mp4" });
await device.decoders.record.info();
await device.decoders.record.start();
await device.decoders.record.stop();

// Snapshot
const jpeg = await device.decoders.snapshot(); // ArrayBuffer

Streams

Stream index ranges from 0 to 4.

await device.streams.get(0);
await device.streams.update(0, { "mode-h264": "TS" });
await device.streams.getSettings(0);
await device.streams.updateSettings(0, { protocol: "srt", udp_port: 9000 });
await device.streams.info(0);
await device.streams.start(0);
await device.streams.stop(0);
await device.streams.startAll();
await device.streams.stopAll();
await device.streams.preview(0);
await device.streams.endPreview(0);
await device.streams.complete(0);

Network

await device.network.wired(0);   // port 0 or 1
await device.network.wifi.getSettings();
await device.network.wifi.updateSettings({ /* ... */ });
await device.network.modem(0);   // index 0-7

Filtering & Describing Settings

Every getSettings() method accepts an optional settings array to request only specific keys, and every resource exposes a matching describeSettings() method to retrieve the description and metadata for settings rather than their current values.

Filter to specific keys

Pass a settings array to receive only those keys in the response:

// Returns only codec and bitrate_list in res.settings
const res = await device.encoders.video.getSettings({ settings: ["codec", "bitrate_list"] });
console.log(res.settings.codec);       // "h264"
console.log(res.settings.bitrate_list); // 20000

This works on all getSettings() methods. For streams, pass the index first:

await device.streams.getSettings(0, { settings: ["protocol", "udp_port"] });

Note: When filtering, only the requested keys will be present in the response. Accessing other keys will return undefined at runtime.

Get setting descriptions

Use describeSettings() to retrieve the description and metadata for settings instead of their current values:

const res = await device.encoders.video.describeSettings();
console.log(res.settings.codec);
// { type: "string", default: "h264", choices: ["h264", "hevc"], ... }

Combine filtering and descriptions

Pass a settings array to describeSettings() to get descriptions for specific keys only:

const res = await device.encoders.video.describeSettings({ settings: ["codec", "bitrate_list"] });

Available on all settings resources

| Resource | getSettings | describeSettings | |---|---|---| | system.firmware | getSettings(options?) | describeSettings(options?) | | encoders.video | getSettings(options?) | describeSettings(options?) | | encoders.audio | getSettings(options?) | describeSettings(options?) | | encoders.metadata | getSettings(options?) | describeSettings(options?) | | encoders.record | getSettings(options?) | describeSettings(options?) | | decoders.video | getSettings(options?) | describeSettings(options?) | | decoders.audio | getSettings(options?) | describeSettings(options?) | | decoders.audio.channel(n) | getSettings(options?) | describeSettings(options?) | | decoders.metadata | getSettings(options?) | describeSettings(options?) | | decoders.record | getSettings(options?) | describeSettings(options?) | | streams | getSettings(index, options?) | describeSettings(index, options?) | | network.wifi | getSettings(options?) | describeSettings(options?) |

Settings Sync

// Import settings from a file
await device.settingsSync.import({
  type: "device_settings_export",
  /* ...settings data... */
});

// Push settings to other devices (max 10)
await device.settingsSync.push({
  targets: ["192.168.1.101", "192.168.1.102"],
  password: "target-device-password",
  settings: { /* ...settings data... */ },
});

Error Handling

The SDK throws typed errors for different HTTP status codes:

import {
  TeradekError,        // Base class for all SDK errors
  AuthenticationError, // 401 — missing or invalid token
  BadRequestError,     // 400 — invalid input
  RateLimitError,      // 429 — rate limit exceeded
  ServerError,         // 500 — device internal error
} from "@teradek/sdk";

try {
  await device.system.info();
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof AuthenticationError) {
    console.log("Invalid credentials or expired token");
  } else if (err instanceof BadRequestError) {
    console.log("Invalid request parameters");
  } else if (err instanceof ServerError) {
    console.log("Device internal error");
  }
}

All error classes extend TeradekError and include:

• status — HTTP status code
• body — raw response body from the device (if available)
• message — human-readable error description

Network-level errors (connection refused, DNS failure, timeouts) are thrown as standard Node.js errors, not TeradekError instances.

Response Format

All API methods return the full response object:

interface ApiResponse<T> {
  status: string;
  message: string;
  timestamp: number;
  settings: T;       // The typed payload
  endpoints?: string[];
}

Access the typed settings directly:

const res = await device.encoders.video.getSettings();
console.log(res.settings.codec);         // "h264"
console.log(res.settings.bitrate_list);  // 20000

Development

Setup

git clone [email protected]:teradek/tdk-dev-sdk-js.git
cd tdk-dev-sdk-js
npm install

Build

npm run build        # Build ESM + CJS to dist/
npm run dev          # Build in watch mode
npm run typecheck    # Type-check without emitting

Testing

Integration tests run against a real Prism device. Create a tests/.env file with your device credentials:

cp tests/.env.example tests/.env
# Edit tests/.env with your device IP and password

npm test             # Run all tests once
npm run test:watch   # Run tests in watch mode

Tests are automatically skipped when no device credentials are configured.

Requirements

• Node.js 18 or later
• Apollo OS 2.25 or later on target device

Documentation

Full API documentation: teradekdev.com

License

MIT