Utiliser .raw pour une fonctionnalité SDK non encore enveloppée

Ce que ça fait

Chaque service de @legba-core/realtime expose une propriété raw : l’instance réelle du client SDK LiveKit sous-jacente, typée exactement comme le SDK l’exporte (jamais any). Elle permet d’appeler directement une méthode native quand la fonctionnalité voulue n’est pas (encore) enveloppée par Legba — sans attendre qu’un billet l’ajoute.

Service	raw
RoomService (createRoomService)	RoomServiceClient
ParticipantService (createParticipantService)	RoomServiceClient (sa propre instance, pas celle de RoomService)
EgressService (createEgressService)	EgressClient
WebhookService (createWebhookService)	WebhookReceiver
LegbaClientRoom (createLegbaRoom, navigateur)	Room (livekit-client)

Exemple : rendre un participant invisible aux autres, à la volée

ParticipantService ne couvre pas (encore) la mise à jour des permissions d’un participant déjà connecté — seulement lister/lire/exclure/couper le micro. Le SDK natif le permet via RoomServiceClient.updateParticipant(), avec le champ hidden de ParticipantPermission (ex. un modérateur qui observe une salle sans apparaître dans la liste des présents côté clients) :

import { createParticipantService } from "@legba-core/realtime";

const participants = createParticipantService({ serverUrl, apiKey, apiSecret });

// Fonctionnalité non enveloppée par ParticipantService : accès direct au
// client natif, sous la responsabilité de l'appelant.
await participants.raw.updateParticipant("salle-demo", "moderateur-observateur", {
  permission: {
    canSubscribe: true,
    canPublish: false,
    canPublishData: false,
    hidden: true,
  },
});

Piège vérifié en écrivant cet exemple : roomAdmin n’existe pas sur ParticipantPermission (le type que updateParticipant accepte) — c’est un champ de VideoGrant, uniquement accordé à la création d’un jeton (AccessToken), jamais modifiable à la volée sur un participant déjà connecté, même via raw. Vérifié directement dans les types de @livekit/protocol avant d’écrire cette recette.

Les autres méthodes de ParticipantService (removeParticipant, muteParticipantMicrophone, …) continuent de fonctionner normalement après cet appel — raw et les méthodes enveloppées partagent la même instance de client, sans effet de bord entre elles.

Pièges

• raw contourne toute validation propre à Legba. Aucune vérification de format de nom de salle, aucun contrôle requestedByRole, aucune erreur LegbaParticipantError/LegbaRoomError/… typée : une erreur du SDK natif remonte telle quelle. C’est un compromis assumé, pas un bug — documenté ici plutôt que « corrigé ».
• Stabilité expérimental, jamais stable. raw suit les évolutions du SDK LiveKit lui-même, hors du contrôle de version de @legba-core/realtime.
• Utiliser raw pour une opération déjà enveloppée par Legba (ex. raw.createRoom(...) au lieu de roomService.createRoom(...)) perd tous les garde-fous de cette méthode (vérification d’existence, validation du nom, etc.) sans aucun bénéfice — préférer la méthode enveloppée dans ce cas.
• Un projet qui n’utilise jamais raw ne paie aucun coût : c’est une référence vers un objet déjà construit par le service, pas une fonctionnalité additionnelle qui s’exécute.