Framework-agnostic state store for Hiyve video conferencing applications. Use with any UI framework (React, Vue, Svelte) or vanilla JavaScript.
npm install @hiyve/core @hiyve/rtc-client
import { HiyveStore } from '@hiyve/core';
// Zero-config -- defaults to POST /api/generate-room-token
const store = new HiyveStore();
// Subscribe to state changes
store.subscribe(() => {
console.log('State changed:', store.getState());
});
// Subscribe to a specific slice
store.subscribeToSlice('room', () => {
const room = store.getSlice('room');
console.log('Room:', room.room?.name, 'In room:', room.isInRoom);
});
// Create or join a room
await store.createRoom('my-room', 'user-123');
// Control media
await store.toggleAudio();
await store.toggleVideo();
// Clean up
store.destroy();
The main class. Create one instance per session.
| Option | Type | Default | Description |
|---|---|---|---|
generateRoomToken |
() => Promise<string> |
auto | Returns a Hiyve room token. Defaults to POST /api/generate-room-token when using @hiyve/admin server middleware |
localVideoElementId |
string |
'local-video' |
ID of the HTML video element for local preview |
connectOptions |
{ videoDeviceId?, audioDeviceId? } |
{} |
Initial device IDs |
persistDeviceChanges |
boolean |
false |
Persist device selections across sessions |
onError |
(error: Error) => void |
- | Error callback |
| Method | Returns | Description |
|---|---|---|
subscribe(listener) |
() => void |
Subscribe to all state changes. Returns unsubscribe function. |
subscribeToSlice(name, listener) |
() => void |
Subscribe to a specific slice. Returns unsubscribe function. |
getState() |
HiyveStoreState |
Get full state snapshot |
getSlice(name) |
Slice value | Get a specific slice snapshot |
getClient() |
Client | null |
Get the raw rtc-client instance |
| Slice | Key Fields |
|---|---|
connection |
isConnected, isConnecting, error |
room |
room, isOwner, isInRoom |
client |
client (Client instance) |
participants |
participants (Map), localUserId |
localMedia |
isAudioMuted, isVideoMuted, isScreenSharing |
recording |
isRecording, recordingId, recordingStartTime |
streaming |
isStreaming, streamingId, streamingUrl |
transcription |
isTranscribing, transcriptions (array) |
chat |
messages (array), unreadCount |
waitingRoom |
waitingUsers, isWaitingForAdmission, wasRejected |
waitForHost |
isWaiting, roomName, timeout |
audioProcessing |
feedbackDetected, audioValidation, gainLevel |
layout |
dominantSpeaker |
handRaise |
raisedHands (Map) |
aiChat |
messages (array) |
intelligence |
isActive, coachingEnabled, coachingVariant, realtimeHints, talkRatio, currentTopic, topicShifts |
storedRooms |
rooms, isLoading, error, lastFetchedAt |
activeRooms |
rooms, isConnected, isLoading, error |
userFiles |
files, isLoading, error, lastFetchedAt |
Room Management: createRoom(), joinRoom(), joinRoomWithToken(), getRoomInfoFromToken(), leaveRoom()
Media Controls: toggleAudio(), toggleVideo(), toggleOutputMute(), startScreenShare(), stopScreenShare()
Devices: setVideoDevice(), setAudioInputDevice(), setAudioOutputDevice()
Recording: startRecording(), stopRecording(), clearRecordingError()
Streaming: startStreaming(), stopStreaming(), switchStreamingUser(), getStreamingUrls(), clearStreamingError()
Transcription: startTranscription(), stopTranscription(), enrichTranscription()
Chat: sendMessage(), sendDataMessage(), clearUnread(), loadChatHistory()
Waiting Room: admitUser(), rejectUser()
Remote Mute: remoteMuteAudio(), remoteMuteVideo(), muteRemoteOutput()
Layout: setDominant(), toggleHandRaised(), lowerAllHands(), setGain()
Intelligence: enableCoaching(), disableCoaching(), updateCoachingData(), dismissHint()
Lifecycle: destroy()
Persistent rooms that can be created, listed, edited, and deleted outside of a live session (dashboard/lobby context).
| Method | Description |
|---|---|
fetchStoredRooms(userId, options?) |
Fetch all stored rooms for a user. Options: { consumerOnly?, offlineOnly? } |
addStoredRoom(options, userId) |
Create a new stored room |
updateStoredRoom(alias, updates, userId) |
Update an existing stored room by alias |
deleteStoredRoom(alias, userId) |
Delete a stored room by alias |
getStoredRoom(alias, userId) |
Fetch a single stored room by alias |
clearStoredRooms() |
Reset stored rooms to initial state (e.g. on user change or logout) |
clearStoredRoomsError() |
Clear the stored rooms error |
Live room discovery -- owners advertise rooms so other users can find and join them in real time.
| Method | Description |
|---|---|
advertiseRoom(cloudClient, options) |
Advertise a room for discovery |
removeAdvertisedRoom(cloudClient, roomName) |
Stop advertising a room |
connectActiveRooms(streamUrl) |
Open an SSE stream for real-time active room updates |
disconnectActiveRooms() |
Close the SSE stream |
fetchActiveRooms(cloudClient, userId?) |
One-shot fetch of active rooms |
Manage user files across all rooms without requiring an active room connection.
| Method | Description |
|---|---|
fetchUserFiles(userId) |
Fetch all files for a user across all rooms |
deleteUserFile(fileId) |
Delete a file by ID |
renameUserFile(fileId, newFilename) |
Rename a file |
moveUserFile(fileId, newLocation) |
Move a file to a different folder |
shareUserFile(fileId, userIds, sharedRoom?) |
Share a file with other users |
createUserFolder(location, roomName?) |
Create a folder |
deleteUserFolder(location) |
Delete a folder |
getUserFileUrl(fileId) |
Get a download URL for a file |
uploadUserFile(file, location, resourceType?) |
Upload a new file |
clearUserFiles() |
Reset user files to initial state (e.g. on user change or logout) |
clearUserFilesError() |
Clear the user files error |
Join token error codes for handling useJoinToken / getRoomInfoFromToken failures:
| Constant | Value | Description |
|---|---|---|
TOKEN_NOT_FOUND |
'TOKEN_NOT_FOUND' |
Token does not exist (HTTP 404) |
TOKEN_EXPIRED |
'TOKEN_EXPIRED' |
Token has expired (HTTP 410) |
INVALID_PASSWORD |
'INVALID_PASSWORD' |
Incorrect room password (HTTP 401) |
USER_NOT_AUTHORIZED |
'USER_NOT_AUTHORIZED' |
User is not allowed to join via this token (HTTP 403) |
ROOM_NOT_ACTIVE |
'ROOM_NOT_ACTIVE' |
Room is not active yet (HTTP 503) |
| Function | Description |
|---|---|
resolveTabsConfig(config, mode) |
Resolves a StoredRoomTabsConfig into a flat TabsFeatureConfig for 'offline' or 'live' mode. Handles structured, legacy flat, and null configs. |
cleanUserId(userId) |
Sanitizes a user ID string for use with the signaling server. Re-exported from @hiyve/rtc-client. |
All types are exported from the package entry point. Key types by category:
| Type | Description |
|---|---|
HiyveStoreOptions |
Constructor options for HiyveStore |
HiyveStoreState |
Full state snapshot returned by getState() |
SliceName |
Union of all valid slice names for subscribeToSlice() / getSlice() |
RoomInfo |
Room metadata (name, owner, participants count, etc.) |
ConnectionState |
Connection status fields (isConnected, isConnecting, error) |
RoomState |
Room state fields (room, isOwner, isInRoom) |
Participant |
Remote participant with streams and mute status |
ParticipantsState |
Participants map and local user ID |
LocalMediaState |
Local audio/video mute and screen share status |
RecordingState |
Recording status, ID, start time, and error |
StreamingState |
Streaming status, ID, URL, and error |
TranscriptionEntry |
Single transcription segment with speaker and timestamp |
TranscriptionState |
Transcription status and entries array |
ChatMessage |
Chat message with sender, text, and timestamp |
ChatState |
Chat messages array and unread count |
AiChatMessage |
AI assistant chat message |
WaitingRoomUser |
User waiting for admission |
WaitingRoomState |
Waiting room users and admission status |
WaitForHostState |
Wait-for-host screen state |
StoredRoom |
Persistent room configuration |
StoredRoomUpdates |
Fields for updating a stored room |
CreateStoredRoomOptions |
Options for creating a stored room |
StoredRoomsState |
Stored rooms list with loading/error state |
StoredRoomTabsConfig |
Tab configuration for stored rooms |
ActiveRoom |
Discovered active room |
ActiveRoomsState |
Active rooms list with connection and loading state |
AdvertiseRoomOptions |
Options for advertising a room for discovery |
FileUploadOptions |
Options for uploading a file |
FileUploadResult |
Result of a file upload (ID, URL) |
FileModifyOptions |
Options for renaming or moving a file |
FileClient |
File operations interface used by components |
FileShareEntry |
File sharing recipient entry |
UserFile |
User file metadata |
UserFilesState |
User files list with loading/error state |
JoinTokenErrorCode |
Union of join token error code strings |
JoinTokenError |
Error object for join token failures |
GetRoomInfoFromTokenOptions |
Options for getRoomInfoFromToken() |
RoomInfoFromToken |
Room info returned from a join token |
ClientState |
Client instance state |
ClientActions |
Available client actions |
ClientContextValue |
Combined state and actions for context consumers |
Utilities for working with additional camera streams (ghost cameras):
| Export | Description |
|---|---|
GHOST_CAMERA_DELIMITER |
Delimiter string used in ghost camera user IDs |
isGhostCamera(userId) |
Check if a user ID represents a ghost camera |
getGhostCameraLabel(userId) |
Extract the display label from a ghost camera user ID |
getGhostCameraOwner(userId) |
Extract the owner's user ID from a ghost camera user ID |
buildGhostCameraUserId(ownerId, label) |
Build a ghost camera user ID from an owner ID and label |
The subscribe() + getSnapshot() contract is the universal primitive for framework integration:
React (via @hiyve/react):
const room = useSyncExternalStore(
cb => store.subscribeToSlice('room', cb),
() => store.getSlice('room'),
);
Vue:
const room = ref(store.getSlice('room'));
const unsub = store.subscribeToSlice('room', () => {
room.value = store.getSlice('room');
});
onUnmounted(unsub);
Svelte:
const room = readable(store.getSlice('room'), set =>
store.subscribeToSlice('room', () => set(store.getSlice('room')))
);
The debug export provides opt-in logging for troubleshooting. Logging is disabled by default.
import { debug } from '@hiyve/core';
// Enable at runtime
debug.enable();
// Check if enabled
debug.isEnabled(); // true
// Disable
debug.disable();
Debug mode can also be enabled via:
HIYVE_DEBUG=true (build time)window.__HIYVE_DEBUG__ = true (runtime)localStorage.setItem('HIYVE_DEBUG', 'true') (persistent)@hiyve/rtc-client as a peer dependency@hiyve/react - React bindings with hooks and ClientProvider