A TypeScript WebSocket client library for Buzz applications
npm install @arena-im/buzz-clientA WebSocket client for Buzz applications that works in Node.js and modern browsers.
``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
`
`ts
import { BuzzClient } from "@arena-im/buzz-client";
const client = new BuzzClient({
namespace: "
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));
`
`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);
`
`html`
- When token is provided, the client exchanges it for a Buzz token.token
- When 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,
});
- 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).
`ts`
const topic = buzzClient.topic("
- emit — send an event on a topic.on
- — listen to an event.off
- — remove a listener.
- 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.
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.
- 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).
-