Web Chat Client SDK

A small client SDK to connect frontend applications to the Web Chat WebSocket server (v3 protocol). Your app is responsible for issuing the JWT token (using the same secret as the server); the SDK connects with that token and exposes events and sendMessage.

Install

npm install webchat-client-sdk

Usage

Obtain a JWT from your backend (signed with the same WEBCHAT_JWT_SECRET as the Web Chat server), then connect and subscribe to events:

import { connectWebChat } from "webchat-client-sdk";

const wc = await connectWebChat({
  url: "wss://your-host/chat/ws",
  token: "eyJhbGc...", // JWT from your backend
});

wc.on("aicw-start-typing", () => {
  console.log("AICW is typing…");
});
wc.on("aicw-end-typing", () => {
  console.log("AICW stopped typing.");
});
wc.on("aicw-message", (msg: string) => {
  console.log(`AICW: ${msg}`);
});
wc.on("user-message", (msg: string) => {
  console.log(`USER: ${msg}`);
});

await wc.sendMessage("Hi there");
// … later
wc.disconnect();

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | required | Full WebSocket URL (e.g. wss://host/chat/ws). | | token | string | required | JWT token. Your backend must sign it with the same secret as the server. | | timezone | string | "UTC" | IANA timezone (e.g. America/New_York). | | keepaliveIntervalMs | number | 45000 | Send ping every N ms. Set to 0 to disable. |

Events

• aicw-start-typing — Server started composing a response.
• aicw-end-typing — Server finished composing.
• aicw-message — AI message text (handler receives string).
• user-message — User message (e.g. echo/broadcast; handler receives string).

Methods

• sendMessage(content: string) — Send a user message to the server.
• disconnect() — Close the WebSocket.

Token

The SDK does not sign or verify JWTs. Your backend (or token endpoint) must:

1. Use the same secret as the Web Chat server (WEBCHAT_JWT_SECRET).
2. Issue a JWT with at least sid (session id), exp, and iat).

The frontend gets the token (e.g. from POST /chat/token with email, or from a login redirect with ?token=...) and passes it to connectWebChat({ url, token }).

Protocol

This SDK implements the v3 WebSocket protocol: subprotocols atlas-web-chat.v3 and jwt.<token>, and the event set user-message, aicw-message, aicw-start-typing, aicw-end-typing, plus optional ping/pong keepalive.

Requirements

• Environment with WebSocket (browser or Node 18+).
• JWT token issued by your backend with the same secret as the server.

platform-jumaross-webchat-sdk