@relaybox/rest

Find the full technical documention here

Welcome to RelayBox.

In order to use this library, you need to create a free account and API key. Find more details here.

If you find any issues, please report them here or contact [email protected].

Installation

To install the REST services library, ensure that npm is installed on the host machine, then run the following command:

npm install @relaybox/rest

Once you have successfully installed the library, the following API reference applies.

RelayBox Constructor

Instantiate a new RelayBox object to enable usage of the server-side SDK.

const relayBox = new RelayBox();

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

RelayBoxOptions

RelayBox class constructor options:

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

License

This project is licensed under the MIT License - see the LICENSE file for details.