JavaScript / TypeScript SDK

Package: whisp-sdk

The Whisp JS/TS SDK is the fastest way to add chat to a web or Node.js application. It wraps the REST API and the realtime WebSocket layer into one friendly, strongly-typed client so you can focus on building your UI — not on plumbing HTTP requests, JWT refresh, or WebSocket reconnection logic.

What you get

The SDK gives you a single WhispClient object with three main responsibilities:

• REST wrapper — every REST endpoint is exposed as a typed async method (whisp.getChats(), whisp.createChat(), whisp.getMessages(), …). No more manual fetch calls, no hand-rolled types.
• Auth state management — setAuth, getAuth, logout, refresh. The SDK stores your JWT in memory and automatically refreshes it when it expires, so your code never has to catch 401s manually.
• Realtime — everything live (new messages, typing indicators, reactions, reads, chat membership changes, …) lives under whisp.realtime.*. The SDK handles the STOMP handshake, ticket fetching, WebSocket reconnection, and exponential backoff for you.

// The full mental model in ~5 lines:
const whisp = new WhispClient({ baseUrl: "..." });
whisp.setAuth({ jwt, refreshToken, userId });     // auth is set
await whisp.realtime.connect();                    // realtime is live
whisp.realtime.on("message", (evt) => { /* … */ }); // listening
await whisp.realtime.sendMessage(chatId, "hi!");   // sending

Who this SDK is for

• Browser frontends (React, Vue, Svelte, vanilla JS) — use the SDK with setAuth() only. Never put an API key in browser code.
• Node.js backends — use the SDK with an API key to register users, sign them in, and forward tokens to your frontend. You can also run realtime from Node.js for things like bots, moderation tools, or integration tests.
• Mobile apps with a JS bridge (React Native, Expo) — same rules as browsers: no API key on the device.

Quick links

• Installation — installing the package (and ws if you need it)
• Quickstart (Browser) — the recommended production flow for web apps
• Quickstart (Node.js) — for use cases where the API key can safely be used
• Authentication — function-by-function reference
• Chats — create, list, manage chats
• Messages — fetch history, paginate, read receipts
• Realtime: receiving events — every event the SDK emits
• Realtime: action methods — sending messages, typing, reactions, …
• Errors & retries
• Troubleshooting

Constructing the client

The simplest possible setup (browser app):

import { WhispClient } from "whisp-sdk";

const whisp = new WhispClient({
  baseUrl: "https://demo.api.whispchat.com",
});

For Node.js backends where it’s safe to hold the API key:

import { WhispClient } from "whisp-sdk";

const whisp = new WhispClient({
  baseUrl: "https://demo.api.whispchat.com",
  apiKey: process.env.WHISP_API_KEY, // server-only, never in browser bundles
});

When do I need webSocketImpl?

This is the most common confusion for new users, so here’s the short rule:

In Node.js, there is historically no built-in WebSocket client. The SDK doesn’t want to force ws as a hard dependency (that would bloat browser bundles for no reason), so instead it asks you to pass in whichever WebSocket implementation you want to use. ws is the de-facto standard and the one we recommend.

import { WhispClient } from "whisp-sdk";
import WebSocket from "ws";

const whisp = new WhispClient({
  baseUrl: "https://demo.api.whispchat.com",
  apiKey: process.env.WHISP_API_KEY,
  webSocketImpl: WebSocket, // only needed if you're running realtime from Node.js
});

Security reminder