@arena-im/buzz-client 1.1.0

package/README.md

@@ -0,0 +1,160 @@
+# buzz-client
+
+A TypeScript WebSocket client for Buzz applications. Works in Node.js and modern browsers. Ships ESM, CJS, and UMD bundles.
+
+## Installation
+
+```bash
+npm i
+npm run build
+```
+
+Bundles are output to `dist/`:
+
+- `dist/buzz-client.esm(.min).js` (ESM)
+- `dist/buzz-client.cjs(.min).js` (CommonJS)
+- `dist/buzz-client.umd(.min).js` (UMD global `window.BuzzClient`)
+
+## Quick start
+
+### Node / Bundlers (ESM or CJS)
+
+```ts
+import { BuzzClient } from "buzz-client"; // if published/installed
+// or from source: import { BuzzClient } from "./dist/buzz-client.esm.js";
+
+const client = new BuzzClient(
+  "prod", // env ("prod" | "dev") or a custom websocket URL
+  "chat", // namespace
+  "<site-id>", // siteId
+  null, // id token (JWT) or null for anonymous
+  { commandTimeout: 15000 }
+);
+
+const topic = client.topic("room:<room-id>");
+const meta = await topic.emit("room_meta:get");
+await topic.on("added", (evt) => console.log("New message", evt));
+```
+
+### Browser (UMD)
+
+```html
+<script src="/dist/buzz-client.umd.js"></script>
+<script>
+  const { BuzzClient } = window.BuzzClient;
+  const client = new BuzzClient("prod", "chat", "<site-id>", null, {
+    commandTimeout: 15000,
+  });
+  const t = client.topic("room:<room-id>");
+  t.emit("room_meta:get").then(console.log);
+  t.on("added", (evt) => console.log("added", evt));
+</script>
+```
+
+See runnable pages in `examples/browser-test.html`, `examples/chat/browser.html` and `examples/comments/browser.html`.
+
+## Examples
+
+- `npm run example:chat`
+- `npm run example:comments`
+
+These scripts use `tsx` to run the examples in `examples/`. You will be prompted for required environment variables if not present:
+
+- `ARENA_SITE_ID`
+- `ARENA_TOKEN` (optional ID token; leave empty for anonymous)
+- Chat: `ARENA_CHAT_ROOM_ID`
+- Comments: `ARENA_SITE_SLUG`, `ARENA_PAGE_ID`
+
+## API
+
+### Constructor
+
+```ts
+new BuzzClient(
+  envOrWebsocketUrl: "prod" | "dev" | string,
+  namespace: string,
+  siteId: string,
+  idToken: string | null,
+  options?: {
+    commandTimeout?: number;
+    websocket?: { headers?: Record<string, string> };
+    identityUrl?: string; // override identity service when using custom ws
+  }
+)
+```
+
+- When `idToken` is provided, the client exchanges it for a Buzz token.
+- When `idToken` is `null`, the client obtains an anonymous token and then exchanges it.
+
+### Core methods
+
+- `topic(name: string): Topic` — helper to work with a specific topic.
+- `subscribe(topic: string): Promise<void>`
+- `unsubscribe(topic: string): Promise<void>`
+- `sendCommand<T>(type: string, topic: string, content?: Record<string, unknown>): Promise<CommandResponse<T>>`
+- `onEvent(topic: string, eventName: string, cb: (event: unknown) => void): void`
+- `clearEventListeners(): void`
+- `disconnect(): Promise<void>` — close connection and clear internal state.
+- `setToken(token: string | null): Promise<void>` — set/refresh the ID token (e.g., after login/logout). This triggers a reconnection.
+
+### Topic API
+
+```ts
+class Topic {
+  emit<T>(
+    eventName: string,
+    content?: Record<string, unknown>
+  ): Promise<EmitResult<T>>;
+  on<T>(eventName: string, callback: (event: T) => void): Promise<void>;
+}
+```
+
+`emit` automatically ensures the topic is subscribed before sending.
+
+### 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 the connection errors, the Buzz client will automatically attempt 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. Defaults: up to 25 requests every 5s per connection. When the window is saturated, the queue waits for the next window.
+
+## Configuration
+
+### Runtime options
+
+- `options.commandTimeout` — default 10s.
+- `options.websocket.headers` — HTTP headers for Node.js `ws` constructor.
+- `options.identityUrl` — override identity service base URL (useful with a custom websocket URL).
+
+### Build-time environment overrides
+
+The build injects environment variables (via `rollup` + `@rollup/plugin-replace`) so you can change default endpoints at build time:
+
+- `BUZZ_WEBSOCKET_URL`, `BUZZ_WEBSOCKET_URL_DEV`
+- `IDENTITY_SERVICE_URL`, `IDENTITY_SERVICE_URL_DEV`
+
+Create a `.env` before `npm run build` to override.
+
+## Development
+
+```bash
+npm i
+npm run build
+# optional: watch
+npm run build:watch
+```
+
+Open the HTML examples under `examples/` from a local static server. Identity endpoints may enforce CORS; test from an allowed origin or proxy if needed.
+
+## Files of interest
+
+- Library entry: `src/lib/index.ts`
+- Token management: `src/lib/token-manager.ts`
+- Reconnect logic: `src/lib/fault_tolerant_websocket.ts`
+- Throttle queue: `src/lib/throttled_queue.ts`
+- Examples: `examples/`