@relaybox/rest NPM

npm version

@relaybox/rest

Find the full technical documention here

Welcome to RelayBox, we're exited you're here!

First up, in order to use this library, you'll need to create a free account and API key. Find more details here.

If you find any issues, please report them here or contact support@relaybox.net.

Installation

To install the REST services library, ensure you have npm running on your machine, then run the following command:

npm install @relaybox/rest

Once you've successfully installed the library, see below for the API reference in more detail or find the full documenation here.

RelayBox Constructor

To begin interactaction with the REST services, instantiate a new RelayBox object.

const relayBox = new RelayBox();

class RelayBox {
  constructor(opts: RelayBoxOptions);
  generateTokenResponse(params: TokenResponseParams): TokenResponse;
  publish(roomId: string | string[], event: string, data: any): Promise<PublishResponseData>;
}

RelayBoxOptions

The various configuration options you'll find throughout the library.

interface RelayBoxOptions {
  apiKey?: string;
}

interface TokenResponseParams {
  clientId?: string | string[];
  expiresIn?: number;
  permissions?: Permission[] | Permissions;
}

interface TokenResponse {
  token: string;
  expiresIn: number;
}

const allowedPermissions: readonly ['subscribe', 'publish', 'presence', 'metrics', 'history', '*'];

type Permission = (typeof allowedPermissions)[number];

interface Permissions {
  [room: string]: string[];
}

generateTokenResponse()

Responsible for generating a secure token to be sent as an HTTP response, which can be exchanged for access to real-time services via @relaybox/client. To learn more about auth tokens, please refer to the Auth Tokens documentation.

relayBox.generateTokenResponse();

Returns string in JWT format

Example:

// Generate a token response with a clientId and custom expiry
const tokenResponse = relayBox.generateTokenResponse({
  clientId: 123,
  expiresIn: 300
});

// Generate a token response attaching dynamic permissions
const permissions = {
  myRoom: [
    'subscribe',
    'publish',
    'presence',
    'metrics',
    'history'
  ];
};

const tokenResponse = relayBox.generateTokenResponse({
  permissions
});

publish()

Responsible for publishing an event to a named "room".

relayBox.publish();

Returns object of type PublishResponseData

interface PublishResponseData {
  timestamp: string;
  signature: string;
}

Example:

const data = {
  hello: 'world'
};

// Publish an event named 'message' to 'room:one' containing data payload
const response = relayBox.publish('room:one', 'message', data);