fishjam-js-server-sdk

name: fishjam-js-server-sdk description: "Node.js / TypeScript server SDK for Fishjam — backends that create rooms, mint peer tokens, listen to server notifications, and run agents. Use when writing a Node.js / Express / Fastify / Hono / NestJS backend that talks to Fishjam, sets up a webhook receiver, runs an AI agent, or generates livestream tokens. Trigger on: '@fishjam-cloud/js-server-sdk', 'FishjamClient', 'FishjamWSNotifier', 'FishjamAgent', 'createPeer', 'createRoom', 'createAgent', 'createVapiAgent', 'createLivestreamStreamerToken', 'createLivestreamViewerToken', 'refreshPeerToken', 'subscribeTracks', 'subscribePeer', 'createMoqToken', 'ServerMessage', 'roomCreated', 'peerAdded', 'trackAdded', 'fishjam backend Node', 'express fishjam', 'fastify fishjam', 'gemini agent fishjam', 'vapi fishjam'. Covers REST, WebSocket notifier, webhook protobuf decoding, FishjamAgent, and Gemini Live integration." license: MIT

Fishjam JS Server SDK

@fishjam-cloud/js-server-sdk — server-side Node.js / TypeScript SDK for the Fishjam platform.

Read ../platform/SKILL.md first. It defines rooms, peers, tracks, management tokens, peer tokens, and the WS-vs-webhook tradeoff that this skill builds on.

Three components

Webhook receivers are not a class — you decode ServerMessage protobuf yourself; covered in webhooks.md.

Install + minimal flow

npm install @fishjam-cloud/js-server-sdk
# or yarn add @fishjam-cloud/js-server-sdk

import { FishjamClient } from '@fishjam-cloud/js-server-sdk';

const fishjamClient = new FishjamClient({
  fishjamId: process.env.FISHJAM_ID!,
  managementToken: process.env.FISHJAM_MANAGEMENT_TOKEN!,
});

const room = await fishjamClient.createRoom();
const { peer, peerToken } = await fishjamClient.createPeer(room.id, {
  metadata: { userId: 'user-123' },
});
// ship `peerToken` to your client

When to read which reference

Key rules

• One FishjamClient per process. It's a thin axios wrapper — share, don't recreate per request.
• Catch SDK exceptions, not axios errors. All methods wrap REST calls in mapException, throwing typed errors (BadRequestException 400, UnauthorizedException 401, RoomNotFoundException / PeerNotFoundException / FishjamNotFoundException 404, ServiceUnavailableException 503, UnknownException for anything else — including 403). All inherit from FishjamBaseException, which is useful for a catch-all instanceof branch. ForbiddenException is exported but never produced by the current mapper. Match on these to map to HTTP status codes. Constructor also throws MissingFishjamIdException synchronously if fishjamId is falsy.
• Management token stays in the backend. Never put it in NEXT_PUBLIC_*, VITE_*, or any bundled env. If exposed, regenerate from the Dashboard.
• Deprecation header. The client logs x-fishjam-api-deprecated once per process. If you see it, plan a migration — don't silence it.
• FishjamWSNotifier does NOT auto-reconnect. The constructor opens one WS; if it closes, you must reinstantiate. Wrap it in a supervisor or use webhooks instead.
• Peer tokens are valid for 24 hours from creation. The token is consumed during the initial WS handshake; an established session keeps running on its own and isn't dropped when the token's wall-clock expiry passes. If the peer hasn't connected yet, or needs to reconnect after the 24h window, call refreshPeerToken to mint a new one and ship it to the client.

References