@100mslive/server-sdk

Node.js Server Side SDK

The 100ms Node.js SDK provides an easy-to-use wrapper around 100ms REST APIs to be used on the server side.

🔧 This is beta, APIs might change

Documentation

Checkout the examples/nodejs folder on root of the repository has some examples on how to use the SDK.

Installation

Install the package with:

# via NPM:
npm install --save @100mslive/server-sdk

# via Yarn:
yarn add @100mslive/server-sdk

Usage

First import the library,

import HMS from "@100mslive/server-sdk";
// OR
import * as HMS from "@100mslive/server-sdk";

Then, the SDK needs to be configured with the Access Key and App Secret from the 100ms Dashboard's Developer Section. This can be done in 2 ways:

1. Passing in the credentials when initializing the SDK.
2. Configuring Environment variables with the credentials, then initializing the SDK.

const hms = new HMS.SDK(accessKey, secret);
// OR
const hms = new HMS.SDK(); // Credentials are in env variables

Environment Variables

HMS_ACCESS_KEY=accessKey123 // access key
HMS_SECRET=secret456 // app secret

Usage with TypeScript

The SDK supports ts, esm and cjs completely. Here's how you can import the types from the SDK and use them.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
// create a room with options -
let roomWithOptions: HMS.Room;
const roomCreateOptions: HMS.Room.CreateOptions = {
  name,
  description,
  template_id,
  recording_info,
  region,
};
roomWithOptions = await hms.rooms.create(roomCreateOptions);

Auth token

You can generate auth token for client SDKs to join a room.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
const tokenConfig = { roomId, role, userId };
console.log(await hms.auth.getAuthToken());
// with additional token options -
const additionalTokenConfig = {
  roomId,
  role,
  userId,
  issuedAt,
  notValidBefore,
  validForSeconds,
};
console.log(await hms.auth.getAuthToken(additionalTokenConfig));

Active room APIs

Here's an example of listing the peers in an active room and then sending a broadcast message to that room, using the active room APIs.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
// list peers in active room -
const peers = await hms.activeRooms.retrieveActivePeers(roomId);
console.log(peers);

// send broadcast message to all peers -
await hms.activeRooms.sendMessage(roomId, { message: "test" });

Analytics APIs

Here's an example of listing track events and recording events, using the analytics APIs.

// list track events by room id and type -
const trackEventFilters: HMS.Analytics.TrackEvent.FilterParams = {
  room_id: "roomId",
  type: ["track.add.success", "track.remove.success"],
};
const trackEventsIterable = hms.analytics.listTrackEvents(trackEventFilters);
for await (const trackEvent of trackEventsIterable) {
  console.log(trackEvent);
}

// list recording events by room id and type -
const recordingEventFilters: HMS.Analytics.RecordingEvent.FilterParams = {
  room_id: "roomId",
  type: "beam.recording.success",
};
const recordingEventsIterable = hms.analytics.listRecordingEvents(recordingEventFilters);
for await (const recordingEvent of recordingEventsIterable) {
  console.log(recordingEvent);
}

External Stream APIs

Here's an example of starting a new external stream in a room and stopping it, using the external stream APIs.

// start a new external stream -
const externalStreamStartParams: HMS.ExternalStream.StartParams = {
  meeting_url: "meetingURL",
  rtmp_urls: ["rtmpURL1", "rtmpURL2"],
};
const newExternalStream = await hms.externalStreams.start("roomId", externalStreamStartParams);

// stop an external stream by id -
const stoppedExternalStream = await hms.externalStreams.stop(newExternalStream.id);
console.log(newExternalStream, stoppedExternalStream);

Live Stream APIs

Here's an example of getting a live stream object and then sending timed metadata to that live stream, using the live stream APIs.

// get a live stream object by its stream id -
const liveStream = await hms.liveStreams.retrieve("streamID");

// send timed metadata to that live stream -
const timedMetadataParams: HMS.LiveStream.TimedMetadataParams = {
  payload: "Hello, this is the message",
  duration: 5000,
};
const sameLiveStream = await hms.liveStreams.sendTimedMetadata(liveStream.id, timedMetadataParams);

console.log(liveStream, sameLiveStream);

Recording Asset APIs

Here's an example of getting a recording asset object and then generating a pre-signed URL to access it, using the recording asset APIs.

// get a recording asset by id -
const recordingAsset = await hms.recordingAssets.retrieve("assetId");

// generate a pre-signed URL to access that -
const preSignedURL = await hms.recordingAssets.generatePreSignedURL(recordingAsset.id);
console.log("URL: " + preSignedURL.url);
console.log("Path: " + preSignedURL.path);

Recording APIs

Here's an example of checking a room's recording and stopping it, using the recording APIs.

// check a recording's room id and stop it -
const recording = await hms.recordings.retrieve("objectID");
if (recording.room_id == "roomID") {
  hms.recordings.stop(recording.id);
} else {
  // stop all recordings in that room -
  const stoppedRecordings = await hms.recordings.stopAll("roomID");
  console.log(stoppedRecordings);
}

Room code APIs

Here's an example of creating room codes for a room and then disabling one of them, using the room code APIs.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
// create room codes -
const roomCodesForRoom = await hms.roomCodes.create(roomId);
console.log(roomCodesForRoom);

// disable a room code -
const disabledRoomCode = await hms.roomCodes.enableOrDisable(roomCodesForRoom[0].code, false);
console.log(disabledRoomCode);

Room APIs

Here's an example for creating and updating a room, using the room APIs in the SDK.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
// creating a room -
const room = await hms.rooms.create();
// with room options -
const roomCreateOptions = {
  name,
  description,
  template_id,
  recording_info,
  region,
};
const roomWithOptions = await hms.rooms.create(roomCreateOptions);

// updating a room -
const roomUpdateOptions = { name };
const updatedRoom = await hms.rooms.update(room.id, roomUpdateOptions);
console.log(room, roomWithOptions, updatedRoom);

Session APIs

Here's an example of listing all the sessions and sessions for a particular room using the session APIs.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
// list sessions associated with a specific room -
const sessionFilters = {
  room_id: "test_room_id",
  limit: 10, // specifies the max no. of objects in one page
  // this means `iterable.isNextCached` will be `false` once every 10 times
};
const sessionsByRoomIterable = hms.sessions.list(sessionFilters);
for await (const session of sessionsByRoomIterable) {
  console.log(session);
  if (!allSessionsIterable.isNextCached) {
    console.log("the next loop is gonna take some time");
  }
}

// get the active session in a room -
try {
  const activeSessionInRoom = hms.sessions.retrieveActiveByRoom("roomId");
  console.log(activeSessionInRoom);
} catch (error) {
  console.log("No active session found in the room!");
}

Errors

Errors will follow the below interface, code is HTTP Status Code.

interface SDKException {
  code?: number;
  name: string;
  message: string;
}

e.g.

const hlsErr = {
  code: 404,
  name: "Not Found",
  message: "hls not running",
};

Currently Supported Endpoints

1. Active Rooms APIs
2. Analytics APIs
3. External Streams APIs
4. Live Streams APIs
5. Recording Assets APIs
6. Recordings APIs
7. Room Codes APIs
8. Rooms APIs
9. Sessions APIs

Make calls to 100ms APIs that the SDK doesn't support yet

If you want to consume an endpoint before it's available in the SDK, feel free to use the api property to make the API calls:

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
const hmsObject = await hms.api.get(path, params);
console.log(hmsObject);

Here's an example of listing the enabled room codes for a room:

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
/**
 * cURL call:
 * `curl --location --request GET 'https://api.100ms.live/v2/rooms/<room_id>' --header 'Authorization: Bearer <management_token>'`
 */
const params = {}; // the request's body goes here
// appropriate header configuration (incl. management token authorization) is handled internally
const room = await hms.api.get(`rooms/${roomId}`, params);
// `room` contains the room object, mapped from response's body
console.log(room);

Management token

If you want to make 100ms API calls on your own without using the api property of SDK, you can generate just the management token to be used for authorization.

import HMS from "@100mslive/server-sdk";

const hms = new HMS.SDK();
console.log(await hms.auth.getManagementToken());
// with token options -
const tokenConfig = {
  issuedAt,
  notValidBefore,
  validForSeconds,
};
console.log(await hms.auth.getManagementToken(tokenConfig));