@relaybox/rest

RelayBox REST SDK

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.

@relaybox/rest

The purpose of this library is to enable seamless integration between your server-side applications and RelayBox's REST services.

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 Class

Instantiate the Relaybox class 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', '*'];

type Permission = (typeof allowedPermissions)[number];

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

Configuration Option	Description	Type
apiKey (required)	Associate an API key with the connection, which you can generate via the dashboard. To create an API key, first register for a free account.	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

Parameter	Description	Default
clientId (optional)	Include a clientId to associate an identity with the token. You must provide a clientId for a connection using the generated token to participate in a room's presence set.	-
expiresIn (optional)	The length of time specified in seconds before the generated token expires and can no longer be used to connect to real-time services	900
permissions (optional)	Optional dynamic permissions overrides specific to the token being generated. To learn more about permissions please see Dynamic Permissions	["*"]

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'
  ];
};

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

Argument	Description	Type
1	**Room Name (required):** The name of the room to publish the event to	string
2	**Event Name (required):** The name of the published event. Connections subscribing to this event by name will receive the event.	string / function
2	**Data (optional):** The data to be sent as the event payload	string / object

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.