buzz-client

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

Installation

$ 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

Node.js or bundlers (ESM or CJS)

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

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

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

Browser (UMD)

<script src="/dist/buzz-client.umd.js"></script>
<script>
  const { BuzzClient } = window.BuzzClient;
  const client = new BuzzClient({
    namespace: "<namespace>",
    siteId: "<site-id>",
    token: null,
  });

  const t = client.topic("room:<room-id>");
  t.emit("room_meta:get").then(console.log);
  t.on("added", (evt) => console.log("added", evt));
</script>

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.

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

Core methods

• topic(name: string): Topic — Subscribe to a specific topic.
• clearEventListeners(): void
• disconnect(): Promise<void> — Close the connection and clear internal state.
• setToken(token: string | null): Promise<void> — Set or refresh the ID token (e.g., after login/logout). This triggers a reconnection.

Topic API

const topic = buzzClient.topic("<topic>");

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

Errors

• 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.

Throttling

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

Runtime options

• 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).