buzz-client

A WebSocket client for Buzz applications that works in Node.js and modern browsers.

Installation

``bash
$ yarn add @arena-im/buzz-client

$ npm i @arena-im/buzz-client

$ bun add @arena-im/buzz-client

$ pnpm add @arena-im/buzz-client
`

Quick start

$3

`ts
import { BuzzClient } from "@arena-im/buzz-client";

const client = new BuzzClient({
namespace: "", // chat | comments
siteId: "",
token: null, // id token (JWT) or null for anonymous
options: { commandTimeout: 15000 },
});

// Example
const t = client.topic(">");
const meta = await t.emit("room_meta:get");
await t.on("added", (evt) => console.log("New message", evt));
`

$3

`ts
import { BuzzClient } from "@arena-im/buzz-client";

const client = new BuzzClient({
namespace: "",
siteId: "",
token: null,
});

// Fetch a temporary-user token and reconnect with it
const buzzToken = await client.setTemporaryUser("guest-username");

// Connection is now active with the returned token
const topic = client.topic("room:");
await topic.emit("room_meta:get");
topic.on("added", console.log);
`

$3

`html


`

API

- When token is provided, the client exchanges it for a Buzz token.
- When token is null, the client obtains an anonymous token and then exchanges it for a Buzz token.

`ts
const buzzClient = new BuzzClient({
namespace: "",
siteId: SITE_ID,
token: null,
});
`

$3

- topic(name: string): Topic — Subscribe to a specific topic.
- clearEventListeners(): void
- disconnect(): Promise — Close the connection and clear internal state.
- setToken(token: string | null): Promise — Set or refresh the ID token (e.g., after login/logout). This triggers a reconnection.
- setTemporaryUser(username: string): Promise — Fetch a temporary-user token from the identity service and reconnect using it (no ID token required).

$3

`ts
const topic = buzzClient.topic("");
`

- emit — send an event on a topic.
- on — listen to an event.
- off — remove a listener.

$3

- CommandTimeoutError — response not received in time.
- CommandErrorResponse — server rejected the command. Has errorType: 'rejected' | 'error' | 'blocked' and message.
- WebsocketError — underlying WebSocket problem. The client auto-reconnects, but in-flight commands are not retried.

> Note: When a connection error occurs, the Buzz client automatically attempts to reconnect. However, commands are not retried after a reconnection — it's up to the caller to handle command retries if needed.

$3

Outgoing commands are rate-limited by an internal queue to align with server-side throttling. Default: up to 25 requests every 5 seconds per connection. When the window is saturated, the queue waits for the next window.

Configuration

$3

- options.commandTimeout — defaults to 10 seconds.
- options.websocket.headers — HTTP headers for the Node.js ws constructor.
- options.identityUrl` — override the identity service base URL (useful with a custom WebSocket URL).