client

client handles connectivity and provides access to the client.realm and client.system namespaces.

All business logic, e.g. creating objects, areas, subscriptions and instructions are related to a given realm and are thus part of a realm object.

import HivekitClient from "@hivekit/client-js";

// Client handles connectivity
const client = new HivekitClient();
await client.connect('wss://api.hivekit.io/v1/ws');
await client.authenticate('my_api_token');

// to use objects, areas, subscriptions etc, get a 
// a realm object from the client
const realm = await client.realm.get('realmId');
await realm.object.create('objId', {label: 'delivery rider', location: {latitude:12.132/*..*/}})

new HivekitClient(options)

Creates a new instance of the Hivekit Client, but does not establish a connection to a server yet.

• options (optional) a map of options to configure the client. Defaults are:

{
    
    /* The time in milliseconds messages are buffered for before they are sent out.
    
    Hivekit's protocol can combine multiple actions, such as creating or updating objects, 
    into a single message that's sent to the server. So even if you call 
    e.g. realm.object.set(data), for multiple objects in a loop, only a single message gets 
    sent out. The default behavior is to send the message immediately after the current 
    JavaScript execution ends (outgoingMessageBufferTime: 0), but you can increase this 
    time to send fewer but bigger messages.*/
    outgoingMessageBufferTime: 0,

    /* If true, the client logs every incoming or outgoing message to the console */
    logMessages: false,

    /* If true, the client logs errors to the console */
    logErrors: true,

    /* The time in milliseconds between heartbeat messages. These are short messages 
    that are continuously passed between client and server to ensure that firewalls, 
    load -balancers and other network hops keep the connection open, to ensure that the server 
    is still responsive and to measure roundtrip latency.*/
    heartbeatInterval: 5000,

    /* Time in milliseconds between reconnection attempts by the client, 
    should the connection be lost.  The first reconnection attempt happens 
    immediately upon connection loss.*/
    reconnectInterval: 1000,

    /* If a WebSocket connection is lost, the client will try to recreate it. It will keep
    doing so every (reconnectInterval) until successful. In certain scenarios however, it might
    be preferable to give up after a number of unsucessful attempts. An example of this would be a 
    user turning on airplane mode for a long flight and your app draining the user's battery
    with endless reconnect attempts.*/
    maxReconnectAttempts: Infinity
}

read-only properties

• client.constants a map of constants used by the client. See https://github.com/hivekit/client-js/blob/main/src/fields.js for a full list.
• client.connectionStatus the current connection status of the client.
• client.ping the time in milliseconds the last heartbeat message took to reach the server and to return.
• client.version the version of the client SDK
• client.serverVersion the version of the server the client is connected to. Available once connectionStatus==authenticated
• client.serverBuildDate the date the server binaries where built. Available once connectionStatus==authenticated
• client.mode the mode the client runs in. Either ws (WebSocket) or http if client.useHTTP() was called.
• client.options the options the client was created with

events

• 'error' an error has occured
• 'ping' the roundtrip latency between client and server has changed
• 'connectionStatusChanged' the connection status has changed

connection states

• 'disconnected' the initial state the client is in - or the final state after client.disconnect() was called. The client will not try to re-establish a connection.
• 'connecting' the client is trying to connect to the server - either as a result of calling client.connect(serverUrl) or due to the loss of a previously established connection.
• 'connected' the client is connected to the server, but the connection is kept in quarantine until client.authenticate(token) is called
• 'authenticated' the client is connected, authenticated and ready for use. This is the one you want :-)
• 'disconnecting' the client is in the process of disconnecting as a result of calling client.disconnect()

client.connect(serverUrl)

Establishes a Websocket connection between the client and the server. This connection will be in a "quarantined" state until client.authenticate(token) is called. If you wish to use the client to make HTTP requests, call client.useHTTP(serverUrl) instead.

• serverUrl the websocket URL to the server, e.g. 'wss://hivekit.io/api/v1/ws' when connecting to Hivekit or 'ws://localhost:8090/ws' when connecting to a local server.
• returns Promise

client.useHTTP(serverUrl)

Primes the client to be used to make HTTP request. This will not establish a connection straight away, but instead remember the serverUrl to be used in future request. Call this INSTEAD of client.connect(serverUrl)

• serverUrl the HTTP URL to the server, e.g. 'https://hivekit.io/api/v1' when connecting to Hivekit or 'http://127.0.0.1:8090/api/v1' when connecting to a local server.
• returns Promise

client.authenticate(token)

Authenticates the connection. You can learn more about authentication here.

• token a JSON Web Token (JWT) string
• returns Promise

client.disconnect()

Closes the current connection

• returns Promise

client.getId(prefix)

Generates a random id with a given prefix

• prefix a string to prefix the id with
• returns string id

client.getURL()

Returns the Websocket URL of the current connection. This might be different from the URL supplied in client.connect(serverUrl) if the browser followed redirects.

client.on(eventName, callbackFunction, context, order)

Subscribe to an event. See above for a list of supported events.

• eventName name of the event
• callbackFunction the function to be invoked when the event occures.
• context (optional) the context with which callbackFunction will be invoked. Usually this. The benefit of having context as an argument is that you do not need to use .bind() or keep a reference to your function to unbind it later.
• order (optional) an integer that defines the order in which multiple listeners for this event will be invoked.

client.off(eventName, callbackFunction, context)

Removes an event callback that was previously registered with client.on()

• eventName name of the event
• callbackFunction the function to be invoked when the event occures.
• context (optional) the context with which callbackFunction will be invoked.