createParticipantService

Ce que ça fait

Crée un client pour gérer les participants d’un serveur LiveKit : lister, lire, exclure, couper le micro à distance, changer un rôle en direct.

Signature

function createParticipantService(config: LiveKitServiceConfig): ParticipantService

Paramètres

Nom	Type	Requis	Défaut	Description
serverUrl	string	oui	—	URL HTTP du serveur LiveKit
apiKey	string	oui	—	Clé API LiveKit
apiSecret	string	oui	—	Secret API LiveKit

Retour

Un ParticipantService avec listParticipants, getParticipant, removeParticipant, muteParticipantMicrophone, changeParticipantRole, et la propriété raw (instance réelle RoomServiceClient du SDK — voir docs/recipes/raw-escape-hatch.md).

Erreurs

Toutes les méthodes peuvent lever LegbaParticipantError (requête invalide, participant introuvable, action non permise) ou LegbaRoomError (ROOM_NOT_FOUND — seulement listParticipants, sur une salle inexistante).

Exemple minimal

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

const participants = createParticipantService({ serverUrl, apiKey, apiSecret });
const list = await participants.listParticipants("salle-demo");

Exemple complet

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

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

// requestedByRole vient de votre propre système d'authentification —
// legba-core ne connaît pas l'identité de l'appelant, seulement son rôle.
try {
  await participants.removeParticipant({
    roomName: "salle-demo",
    identity: "trouble-fete",
    requestedByRole: currentUser.role, // "host" | "participant" | "viewer"
  });
} catch (error) {
  if (error instanceof LegbaParticipantError) {
    console.error(error.code, error.message);
  }
}

Pièges

• requestedByRole est vérifié par @legba-core/realtime, pas par LiveKit. Le SDK serveur LiveKit (RoomServiceClient) est toujours authentifié en admin complet — il n’y a pas de notion de « qui demande » à ce niveau. C’est notre couche qui refuse l’action si requestedByRole !== "host", avant tout appel réseau. Un backend appelant doit donc déterminer le rôle de l’utilisateur lui-même (session, base de données, etc.) avant d’appeler removeParticipant/muteParticipantMicrophone.
• muteParticipantMicrophone cherche la piste dont la source est microphone : si le participant ne publie pas encore de piste micro (n’a pas encore rejoint via @legba-core/realtime côté client, LGB-013), l’appel lève LegbaParticipantError plutôt que d’échouer silencieusement.
• listParticipants vérifie explicitement que la salle existe avant d’interroger les participants : LiveKit rend un tableau vide pour une salle inexistante comme pour une salle vide, ce qui masquerait l’erreur sans cette vérification.
• changeParticipantRole ne peut jamais accorder roomAdmin. Ce grant vit uniquement dans le jeton (VideoGrant), jamais dans les droits live-modifiables du SDK LiveKit (ParticipantPermission n’a pas ce champ, vérifié dans le SDK) — accorder roomAdmin exige de réémettre un jeton et de faire reconnecter le participant. changeParticipantRole met à jour uniquement canPublish/canSubscribe/canPublishData (droits média) et marque le rôle dans les métadonnées du participant, pour que le backend puisse le consulter lors de ses propres décisions d’autorisation (requestedByRole) — jamais pour que LiveKit lui-même reconnaisse ce participant comme administrateur.
• changeParticipantRole couvre à la fois promotion et rétrogradation — une seule fonction, même mécanisme quel que soit le sens.
• raw est sa propre instance RoomServiceClient, distincte de celle exposée par RoomService.raw (aucun singleton partagé entre services, même avec la même config). C’est une échappatoire expérimentale : l’utiliser contourne toute validation propre à Legba (requestedByRole compris) — voir docs/recipes/raw-escape-hatch.md.

Voir aussi

• createRoomService
• LegbaParticipantError