@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[];
}

Configuration Option	Description	Type
apiKey (required)	An API key plays an important role in identitfying your app when publising events or conneciing to the realtime services. Head over to the dashboard to register for a free account and create an API key if you havn't already.	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',
    '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;
}

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.