Add more doc comments

src/livekit/auth/csApi.ts

@@ -21,12 +21,28 @@ export type ClientGetTokenParts = Pick<
 >;
 
 export interface GetSFUConfigParams {
+  /**
+   * The Matrix client.
+   */
   client: ClientGetTokenParts;
+  /**
+   * Data identifying the local user's session membership.
+   */
   membership: CallMembershipIdentityParts;
+  /**
+   * The WebSocket URL of the SFU for which we wish to get an access token.
+   */
   url: string;
+  /**
+   * The ID of the Matrix room in which the session takes place.
+   */
   roomId: string;
 }
 
+/**
+ * Gets an {@link SFUConfig} appropriate for connecting to a given SFU, using
+ * the MSC4195 LiveKit client-server API endpoints.
+ */
 export async function getSFUConfig({
   client,
   membership,
@@ -50,13 +66,33 @@ export type ClientDelegationParts = Pick<
 >;
 
 export interface DelegateDelayedLeaveParams {
+  /**
+   * The Matrix client.
+   */
   client: ClientDelegationParts;
+  /**
+   * Data identifying the local user's session membership.
+   */
   membership: CallMembershipIdentityParts;
+  /**
+   * The WebSocket URL of the SFU to which we are publishing and wish to
+   * delegate the delayed leave event.
+   */
   url: string;
+  /**
+   * The ID of the room in which the session takes place.
+   */
   roomId: string;
+  /**
+   * The delay ID of the leave event to be delegated.
+   */
   delayId: string;
 }
 
+/**
+ * Delegates a delayed leave event to a given SFU, so that the event will
+ * be sent on our behalf whenever we disconnect from the SFU.
+ */
 export async function delegateDelayedLeave({
   client,
   membership,

src/livekit/auth/index.ts

@@ -38,14 +38,32 @@ function isEndpointUnsupported(e: unknown): boolean {
 }
 
 export interface GetSFUConfigParams {
+  /**
+   * The Matrix client.
+   */
   client: csApi.ClientGetTokenParts & openID.ClientOpenIDParts;
+  /**
+   * Data identifying the local user's session membership.
+   */
   membership: CallMembershipIdentityParts;
+  /**
+   * The transport for which we wish to get an access token.
+   */
   transport: UnstableLivekitTransport;
+  /**
+   * The ID of the Matrix room in which the session takes place.
+   */
   roomId: string;
+  /**
+   * Whether we want to publish or only subscribe on the {@link transport}.
+   */
   role: "publisher" | "subscriber";
   logger: Logger;
 }
 
+/**
+ * Gets an {@link SFUConfig} appropriate for connecting to a given transport.
+ */
 export async function getSFUConfig({
   client,
   membership,
@@ -64,6 +82,10 @@ export async function getSFUConfig({
       });
     } catch (e) {
       if (isEndpointUnsupported(e)) {
+        // Publishers should never fall back. If a homeserver advertises a `url`
+        // but doesn't support MSC4195 itself, that's a misconfiguration which
+        // the admin should know about so they can prepare for the future
+        // deprecation of `livekit_service_url`.
         const mayFallBack =
           role === "subscriber" && "livekit_service_url" in transport;
         if (mayFallBack) {
@@ -94,14 +116,34 @@ export async function getSFUConfig({
 }
 
 export interface DelegateDelayedLeaveParams {
+  /**
+   * The Matrix client.
+   */
   client: csApi.ClientDelegationParts & openID.ClientOpenIDParts;
+  /**
+   * Data identifying the local user's session membership.
+   */
   membership: CallMembershipIdentityParts;
+  /**
+   * The transport to which we are publishing and wish to delegate the delayed
+   * leave event.
+   */
   transport: UnstableLivekitTransport;
+  /**
+   * The ID of the room in which the session takes place.
+   */
   roomId: string;
+  /**
+   * The delay ID of the leave event to be delegated.
+   */
   delayId: string;
   logger: Logger;
 }
 
+/**
+ * Delegates a delayed leave event to a given transport, so that the event will
+ * be sent on our behalf whenever we disconnect from the transport's SFU.
+ */
 export async function delegateDelayedLeave({
   client,
   membership,

src/livekit/auth/openID.ts

@@ -27,7 +27,7 @@ export type ClientOpenIDParts = Pick<
 export interface GetSFUConfigParams {
   client: ClientOpenIDParts;
   /**
-   * Our own membership identity parts used to send to the JWT service.
+   * Data identifying the local user's session membership.
    */
   membership: CallMembershipIdentityParts;
   /**
@@ -35,12 +35,11 @@ export interface GetSFUConfigParams {
    */
   serviceUrl: string;
   /**
-   * The room ID used in the request. This is NOT the livekit_alias. The JWT
+   * The ID of the Matrix room in which the session takes place.
-   * service will provide the alias. It maps Matrix room IDs to LiveKit aliases.
    */
   roomId: string;
   /**
-   * Whether we want to publish or only subscribe on this transport.
+   * Whether we want to publish or only subscribe on the {@link transport}.
    */
   role: "publisher" | "subscriber";
   /**
@@ -55,10 +54,8 @@ export interface GetSFUConfigParams {
 }
 
 /**
- * Gets a bearer token from the homeserver and then use it to authenticate
+ * Gets an {@link SFUConfig} appropriate for connecting to the SFU behind a
- * to the matrix RTC backend in order to get acces to the SFU.
+ * given service URL, using the legacy OpenID flow.
- * It has built-in retry for calls to the homeserver with a backoff policy.
- * @returns Object containing the token information
  * @throws FailToGetOpenIdToken
  */
 export async function getSFUConfig({
@@ -123,6 +120,11 @@ export async function getSFUConfig({
   }
 }
 
+/**
+ * Gets a JWT token appropriate for connecting to the SFU behind a given service
+ * URL, using the legacy `/sfu/get` endpoint, which assigns us a legacy
+ * (`<user_id>:<device_id>`) participant identity.
+ */
 async function getLiveKitJWTLegacy(
   membership: CallMembershipIdentityParts,
   livekitServiceURL: string,
@@ -198,6 +200,11 @@ class NotSupportedError extends Error {
   }
 }
 
+/**
+ * Gets a JWT token appropriate for connecting to the SFU behind a given service
+ * URL, using the default `/get_token` endpoint, which assigns us a hashed
+ * (pseudonymised) participant identity.
+ */
 async function getLiveKitJWT(
   membership: CallMembershipIdentityParts,
   livekitServiceURL: string,