@relaybox/client

The purpose of this library is to enable seamless integration between your client-side applications and RelayBox's real-time services infrastructure.

Installation

To install the client library SDK, ensure you have npm installed on the host machine and run the following command:

npm install @relaybox/client

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

RelayBox Class

Instantiate the Relaybox class to make an initial connection

const relayBox = new RelayBox();

class Relaybox {
  constructor(opts: RelayBoxOptions);
  connect(): Promise<void>;
  readonly connection: EventEmitter;
  clientId?: string | number;
  connectionId: string | null;
  quickConnect(): Promise<void>;
  join(roomId: string): Promise<Room>;
  disconnect(): void;
}

RelayBoxOptions

RelayBox class constructor options:

interface RelayBoxOptions {
  apiKey?: string;
  clientId?: number | string;
  authEndpoint?: string;
  authAction?: (params: any) => Promise<TokenResponse>;
  authParams?: AuthParamsOrHeaders | null;
  authHeaders?: AuthParamsOrHeaders | null;
  authRequestOptions?: AuthRequestOptions;
  authTokenLifeCycle?: AuthTokenLifeCycle;
}

type AuthParamsOrHeaders = Record<string, unknown> | (() => Record<string, unknown> | null);

interface AuthRequestOptions {
  method?: 'GET' | 'POST';
  mode?: 'cors' | 'navigate' | 'no-cors' | 'same-origin' | null;
  credentials?: 'include' | 'omit' | 'same-origin' | null;
  cache?: 'no-cache' | 'reload' | 'force-cache' | 'only-if-cached' | null;
  redirect?: 'follow' | 'manual' | 'error' | null;
  referrerPolicy?:
    | 'no-referrer'
    | 'no-referrer-when-downgrade'
    | 'origin'
    | 'origin-when-cross-origin'
    | 'same-origin'
    | 'strict-origin'
    | 'strict-origin-when-cross-origin'
    | 'unsafe-url'
    | null;
  body?: string;
}

type AuthTokenLifeCycle = 'session' | 'expiry';

Configuration Option	Description	Type
apiKey (optionial / not recommended)	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. While API keys allow connection to Relaybox services, using authentication tokens is advisable for enhanced security.	string
clientId (optionial / not recommended)	Include a clientId to associate an identity with the connection. You must provide a clientId for the connection to participate in a room's presence set.	string or number
authEndpoint (optional / recommended)	Specify the URL of the endpoint that the client should call to obtain an authentication token, enabling connection to your application. For example, use /user/auth. This endpoint is tasked with issuing a signed token, which is generated using the @relaybox/rest library.	string
authAction (optional / recommended)	Specify a server action that returns a token response. Aimed at NextJS integrations using App Router server actions. Send additional data as an optional argument using the authParams option. The server action is tasked with issuing a signed token, which is generated using the @relaybox/rest library.	string
authParams (conditional)	Used in conjunction with the authEndpoint or authActionto send additional data with the authentication token request through URL query parameters or function arguments. For example, /auth/user?id=123. The value can be either an object or a function that returns an object.	object or function returning object
authHeaders (conditional)	This is used alongside the authEndpoint to include additional data within the request headers when obtaining an authentication token response.	object or function returning object
authRequestOptions (conditional)	Options for the JavaScript Fetch API that are sent along with the authentication token request.	JS Fetch API compatible object
region (optional)	Specify the closest geographical region to your location. When set, the connection will enter the network through this designated edge entry point.	string
authTokenLifeCycle (optional / expiremental) default: session	When set to 'expiry', the token will be refreshed upon expiration, and the connection will be re-established with the new token. When set to 'session', the authentication token will remain valid for the duration of the session and will only be refreshed upon establishing a new connection if the token has expired.	'session' \| 'expiry'

Connection

To connect to RelayBox services, you need to import the base class into your scripts as follows:

// esm
import { RelayBox } from '@relaybox/client';

// commonJs
const { RelayBox } = require('@relaybox/client');

Connection Events

To assist with managing the connection lifecycle, several connection events are available to attach listeners to.

enum SocketEvent {
  CONNECT = 'connect',
  DISCONNECT = 'disconnect',
  ERROR = 'error',
  CONNECT_FAILED = 'connect_failed',
  RECONNECTING = 'reconnecting',
  RECONNECTED = 'reconnected',
  RECONNECT_FAILED = 'reconnect_failed'
}

Event Name	Description
connect	Emitted when a connction moves to a connected state. This could be following an initial connection or reconection event.
disconnect	Emitted when a connection moves to a disconnected state. This could be intentional or following a network event. The connection will attempt to reconnect using an exponential backoff for a maximum of 10 retries.
error	Emitted when a connection error is received.
connect_failed	Emitted in the event a connection is unable to be established.
reconnecting	Emitted when a connection moves to a reconnecting state following a disconnection event.
reconnected	Emitted following a sucessful reconnection.
reconnect_failed	Emitted after reconection attempts is equal to maximum numebr of retries

connect()

Asynchronous function to invoke a connection to RelayBox real-time services.

// Promise<void>
await relayBox.connect();