JavaScript SDK / Installation

Installation#

@zeligate/zeli-avatar is the JavaScript and TypeScript SDK for a Zeli avatar box. It has zero runtime dependencies: a browser already ships WebRTC, WebSockets and fetch, which is everything the session client uses.

Install#

npm install @zeligate/zeli-avatar

The package is @zeligate/zeli-avatar on npm, where you can see the released versions. It is published from this repository's release workflow through GitHub's OIDC, so there is no long lived npm token on anyone's machine and the published files are the ones the tagged build produced.

The package is published with TypeScript declarations, so editors resolve types without a separate @types install.

Requirements#

• A running Zeli avatar box and its base URL, for example https://your-box.example.com. The URL must start with http:// or https://, and the client throws a ConfigurationError if it does not.
• Network access from the runtime to the box for both HTTP signalling and the WebRTC media connection.
• A credential. In a browser that is a short-lived session token, never a full API key. See Authentication.

Browsers#

Nothing extra to install. The SDK uses only platform APIs:

Node#

Node has fetch from v18 and a global WebSocket from v22, but it has no WebRTC. Supply an implementation:

npm install @zeligate/zeli-avatar werift

import { RTCPeerConnection } from "werift";
import { ZeliClient, type RTCPeerConnectionLike } from "@zeligate/zeli-avatar";
 
const client = new ZeliClient({
  serverUrl: process.env.ZELI_BOX_URL!,
  apiKey: process.env.ZELI_API_KEY,
  peerConnectionFactory: (config) =>
    new RTCPeerConnection(config) as unknown as RTCPeerConnectionLike,
});

On Node before v22, pass webSocketFactory as well. The package declares "engines": { "node": ">=18" }.

Verify#

import { ZeliClient, ZeliEvent } from "@zeligate/zeli-avatar";
 
const client = new ZeliClient({ serverUrl: "https://your-box.example.com" });
console.log(Object.keys(ZeliEvent).length, "events available");

Next: the Quickstart.