@legba-core/realtime

Ce que ça fait

Émission de jetons d’accès LiveKit, gestion du cycle de vie des salles, des participants, du chat, de l’enregistrement (egress), des webhooks et des salles de sous-groupe (côté serveur), et connexion client dans le navigateur.

Deux points d’entrée, jamais mélangés

Import	Environnement	Contenu
@legba-core/realtime	Serveur Node (livekit-server-sdk)	Jetons, salles, participants, chat, egress, webhooks, rôles, salles de sous-groupe
@legba-core/realtime/client	Navigateur (livekit-client)	createLegbaRoom

Un backend Node ne doit jamais importer /client, un bundle navigateur ne doit jamais importer l’entrée par défaut : chaque entrée est son propre bundle tsup, sans code de l’autre environnement à l’intérieur.

Symboles publics — @legba-core/realtime (serveur)

Jetons d’accès et rôles

Symbole	Rôle
createAccessToken	Construit et signe un jeton d’accès
DEFAULT_TOKEN_TTL_SECONDS	Durée de vie par défaut d’un jeton
PARTICIPANT_ROLES	Les trois rôles acceptés
permissionsForRole	Les permissions média d’un rôle
resolveRole	Résout un rôle externe vers un ParticipantRole Legba, via une politique
LegbaTokenError	Erreur de requête de jeton invalide
TOKEN_ERROR_CODES	Codes d’erreur liés aux jetons
LegbaRolePolicyError	Erreur de politique de rôle mal configurée
ROLE_POLICY_ERROR_CODES	Codes d’erreur liés aux politiques de rôle

Salles

Symbole	Rôle
createRoomService	Crée un client de gestion des salles
LegbaRoomError	Erreur de gestion de salle
ROOM_ERROR_CODES	Codes d’erreur liés aux salles
hashRoomPasscode	Hache un code d’accès de salle
verifyRoomPasscode	Vérifie un code d’accès contre son hachage
setRoomPasscode	Protège une salle avec un code d’accès
clearRoomPasscode	Retire la protection par code d’accès
isRoomProtected	Indique si une salle est protégée par un code

Participants

Symbole	Rôle
createParticipantService	Crée un client de gestion des participants
LegbaParticipantError	Erreur de gestion de participant
PARTICIPANT_ERROR_CODES	Codes d’erreur liés aux participants
computeParticipantSessions	Reconstruit les sessions de participants depuis des événements webhook
summarizeSessionsByGroup	Agrège des sessions de participants par groupe

Salles de sous-groupe (breakout rooms)

Symbole	Rôle
planBreakoutRooms	Planifie une répartition en salles de sous-groupe (pur, sans réseau)
createBreakoutRooms	Crée réellement les salles de sous-groupe planifiées
DEFAULT_BREAKOUT_ROOM_NAME_PREFIX	Préfixe par défaut des noms de salles de sous-groupe

Chat

Symbole	Rôle
createChatService	Crée un service de chat, adossé à un ChatStore
createInMemoryChatStore	Stockage de chat en mémoire (tests, démo)
createMongoChatStore	Stockage de chat persistant sur MongoDB
DEFAULT_CHAT_PAGE_SIZE	Taille de page par défaut pour lister les messages
LegbaChatError	Erreur de chat
CHAT_ERROR_CODES	Codes d’erreur liés au chat

Egress (enregistrement)

Symbole	Rôle
createEgressService	Crée un client de gestion de l’enregistrement (egress)
LegbaEgressError	Erreur d’egress
EGRESS_ERROR_CODES	Codes d’erreur liés à l’egress

Webhooks

Symbole	Rôle
createWebhookService	Vérifie et traite les webhooks LiveKit, avec idempotence
createInMemoryWebhookIdempotencyStore	Stockage d’idempotence en mémoire (tests, démo)
LegbaWebhookError	Erreur de webhook
WEBHOOK_ERROR_CODES	Codes d’erreur liés aux webhooks

Symboles publics — @legba-core/realtime/client (navigateur)

Symbole	Rôle
createLegbaRoom	Crée un client de connexion (salle, pistes, événements)
LegbaClientError	Erreur du client de connexion
CLIENT_ERROR_CODES	Codes d’erreur liés au client

Installation

pnpm add @legba-core/realtime

Pièges

• Le serveur LiveKit applique une tolérance d’une minute sur l’expiration des jetons (jwt.WithLeeway(time.Minute), côté serveur) : un jeton n’est vraiment refusé qu’après ce délai, jamais immédiatement à exp.
• La permission roomAdmin d’un rôle n’apparaît pas dans la réponse de connexion du serveur (participant.permission) : elle est vérifiée par le serveur au moment d’une action d’administration, pas à la connexion.
• Le serveur doit être configuré avec room.auto_create: false, sinon closeRoom semble ne rien faire (la salle est recréée au prochain jeton valide qui tente de la rejoindre).
• removeParticipant/muteParticipantMicrophone vérifient requestedByRole côté @legba-core/realtime, pas côté serveur LiveKit — voir createParticipantService.
• planBreakoutRooms est pur (aucun réseau) ; createBreakoutRooms crée réellement les salles planifiées via RoomService — deux étapes volontairement séparées, jamais fusionnées.
• Chaque service (RoomService, ParticipantService, EgressService, WebhookService) expose une propriété raw vers le client SDK natif correspondant, pour une fonctionnalité pas encore enveloppée — voir docs/recipes/raw-escape-hatch.md.