@vuilabs/rtc-web-sdk

Frontend Web SDK for the lunalabs RTC platform (LiveKit-based voice agents).

Business pages (e.g. api-platform-website ai-chat) talk to api-gateway through this SDK and never need to touch livekit-client directly.

Install

npm install @vuilabs/rtc-web-sdk livekit-client

livekit-client is a peer dep already shipped as a regular dep of this package.

Usage

import { RTCSession } from '@vuilabs/rtc-web-sdk';

const session = new RTCSession({
  endpoint: '/api/voice/v1/luna',
  authHeaders: { Authorization: `Bearer ${jwt}` },
  metadata: { timbre: 'default', language: 'zh' },
});

session.on('status', (s) => console.log('agent:', s));
session.on('firstByte', (ms) => analytics.track('first_byte', { ms }));
session.on('subtitle', (s) => render(s));
session.on('ended', (reason) => message.info(`通话结束: ${reason}`));
session.on('error', (err) => console.error(err.code, err.message));

await session.start();

// later
session.muteAi(true);
session.muteSelf(true);
await session.stop('user_hangup');

Events

| Event | Payload | Source | |---|---|---| | status | 'listening' / 'speaking' / 'thinking' | Bot Data Channel | | firstByte | number (ms) | Bot Data Channel | | userInterrupt | – | Bot Data Channel | | subtitle | { text, definite, paragraph?, id? } | Bot Data Channel | | event | (name, data) — fallback for any unknown event (e.g. set_avatar) | Bot Data Channel | | connectionStateChanged | 'idle' / 'connecting' / 'connected' / 'reconnecting' / 'closed' | SDK | | error | RTCError { code, message } | SDK | | ended | reason string | SDK |

reason values for ended: user_stop / heartbeat_timeout / balance_exhausted / worker_crashed / dispatch_failed / token_expired / network_lost / shutdown.

balance_exhausted arrives via LiveKit Disconnected (not the Data Channel).

RTCError codes

| Code | Trigger | |---|---| | AUTH_FAILED | HTTP 401 | | INSUFFICIENT_BALANCE | HTTP 402 | | CAPACITY_EXCEEDED | HTTP 503 | | NETWORK | other HTTP errors / fetch throw | | UNKNOWN | anything else |

Backend contract

The SDK calls three endpoints under the configured endpoint:

POST {endpoint}/start
POST {endpoint}/heartbeat
POST {endpoint}/stop

See rtc-service-design.md §6.8 for full request / response shapes.

Build / Test

npm install
npm run build
npm test