@comm-baas/server-sdk

Server-side Node.js SDK for the EthioConnect platform. Provides typed methods for token minting, room management, presence queries, analytics, and billing. Authenticates using a tenant API key.

Requirements

• Node.js 18 or later (uses the native fetch API)

Installation

npm install @comm-baas/server-sdk

The @comm-baas/types package is installed automatically as a dependency.

Quick Start

import { CommBaasServer } from '@comm-baas/server-sdk';

const client = new CommBaasServer({
  apiKey: process.env.COMM_BAAS_API_KEY!,
  baseUrl: 'https://api.comm-baas.example.com',
});

const { access_token, expires_in } = await client.auth.mintToken({
  user_id: 'usr_123',
  display_name: 'Alice',
});

Configuration

Option	Type	Required	Default	Description
apiKey	string	Yes	--	Tenant API key in the format cb_<prefix>.<secret>.
baseUrl	string	Yes	--	Base URL of the EthioConnect API (no trailing slash).
timeout	number	No	30000	Per-request timeout in milliseconds.

API Reference

client.auth

Method	Signature	Description
mintToken	(req: MintTokenRequest) => Promise<MintTokenResponse>	Mint a short-lived JWT for an end-user.

client.rooms

Method	Signature	Description
create	(req: CreateRoomRequest) => Promise<CreateRoomResponse>	Create a new room.
list	(params?: ListRoomsParams) => Promise<{ data: Room[]; pagination: PaginationMeta }>	List rooms for the tenant.
get	(roomId: string) => Promise<Room>	Get a single room by ID.
delete	(roomId: string) => Promise<void>	Soft-delete a room.
join	(roomId: string) => Promise<JoinResponse>	Join a room and receive signaling credentials.
leave	(roomId: string) => Promise<void>	Leave a room.
listParticipants	(roomId: string) => Promise<Participant[]>	List current participants.
muteParticipant	(roomId: string, userId: string, req: MuteRequest) => Promise<void>	Mute a participant.
unmuteParticipant	(roomId: string, userId: string) => Promise<void>	Unmute a participant.
kickParticipant	(roomId: string, userId: string, req: KickRequest) => Promise<void>	Kick a participant.
banParticipant	(roomId: string, userId: string, req: BanRequest) => Promise<void>	Ban a user.
unbanParticipant	(roomId: string, userId: string) => Promise<void>	Remove a ban.
setParticipantRole	(roomId: string, userId: string, req: SetRoleRequest) => Promise<void>	Change a participant's role.
startRecording	(roomId: string) => Promise<Recording>	Start recording.
stopRecording	(roomId: string) => Promise<void>	Stop recording.
listRecordings	(roomId: string) => Promise<Recording[]>	List recordings.

client.presence

Method	Signature	Description
room	(roomId: string) => Promise<RoomPresence>	Presence snapshot for a room.
user	(userId: string) => Promise<UserPresence>	Online status and current room for a user.
tenantSummary	(tenantId: string) => Promise<TenantPresenceSummary>	Aggregated presence summary.

client.analytics

Method	Signature	Description
roomQuality	(roomId: string) => Promise<RoomQuality>	Aggregated QoS metrics for a room.
sessionSummary	(sessionId: string) => Promise<SessionSummary>	Full session summary.
tenantOverview	(params?: TenantOverviewParams) => Promise<TenantOverview>	High-level analytics overview.

client.billing

Method	Signature	Description
usage	(params?: UsageParams) => Promise<UsageResponse>	Retrieve usage data.

Error Handling

All API errors are thrown as typed error classes extending CommBaasError:

import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  NetworkError,
} from '@comm-baas/server-sdk';

try {
  await client.rooms.get('room_nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Room not found:', err.errorCode, err.requestId);
  } else if (err instanceof RateLimitError) {
    console.log('Rate limited, retry after:', err.retryAfter, 'seconds');
  }
}

Error Class	HTTP Status	When
AuthenticationError	401	API key missing, invalid, or revoked.
AuthorizationError	403	Insufficient permissions.
NotFoundError	404	Resource does not exist.
ValidationError	422	Request body failed validation.
RateLimitError	429	Rate limit exceeded. Includes retryAfter.
NetworkError	--	DNS, timeout, connection refused.
CommBaasError	Other	Base class for any other HTTP error.

Automatic Retries

The HTTP client retries on 429 and 5xx with exponential backoff (1s, 2s, 4s) for up to 3 attempts. Retry-After headers are respected on 429 responses. Network failures and timeouts are also retried.