livekit-server-sdk 2.6.1 → 2.7.0

package/src/EgressClient.ts

@@ -1,20 +1,22 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import {
+import type {
   DirectFileOutput,
-  EgressInfo,
   EncodedFileOutput,
   EncodingOptions,
   EncodingOptionsPreset,
   ImageOutput,
+  SegmentedFileOutput,
+  StreamOutput,
+} from '@livekit/protocol';
+import {
+  EgressInfo,
   ListEgressRequest,
   ListEgressResponse,
   ParticipantEgressRequest,
   RoomCompositeEgressRequest,
-  SegmentedFileOutput,
   StopEgressRequest,
-  StreamOutput,
   TrackCompositeEgressRequest,
   TrackEgressRequest,
   UpdateLayoutRequest,
@@ -22,7 +24,8 @@ import {
   WebEgressRequest,
 } from '@livekit/protocol';
 import ServiceBase from './ServiceBase.js';
-import { Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
+import type { Rpc } from './TwirpRPC.js';
+import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
 
 const svc = 'Egress';
 
@@ -118,9 +121,9 @@ export class EgressClient extends ServiceBase {
   private readonly rpc: Rpc;
 
   /**
-   * @param host hostname including protocol. i.e. 'https://cluster.livekit.io'
-   * @param apiKey API Key, can be set in env var LIVEKIT_API_KEY
-   * @param secret API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param host - hostname including protocol. i.e. 'https://cluster.livekit.io'
+   * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
+   * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
    */
   constructor(host: string, apiKey?: string, secret?: string) {
     super(apiKey, secret);
@@ -128,9 +131,9 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param roomName room name
-   * @param output file or stream output
-   * @param opts RoomCompositeOptions
+   * @param roomName - room name
+   * @param output - file or stream output
+   * @param opts - RoomCompositeOptions
    */
   async startRoomCompositeEgress(
     roomName: string,
@@ -210,9 +213,9 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param url url
-   * @param output file or stream output
-   * @param opts WebOptions
+   * @param url - url
+   * @param output - file or stream output
+   * @param opts - WebOptions
    */
   async startWebEgress(
     url: string,
@@ -256,9 +259,9 @@ export class EgressClient extends ServiceBase {
   /**
    * Export a participant's audio and video tracks,
    *
-   * @param roomName room name
-   * @param output one or more outputs
-   * @param opts ParticipantEgressOptions
+   * @param roomName - room name
+   * @param output - one or more outputs
+   * @param opts - ParticipantEgressOptions
    */
   async startParticipantEgress(
     roomName: string,
@@ -288,9 +291,9 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param roomName room name
-   * @param output file or stream output
-   * @param opts TrackCompositeOptions
+   * @param roomName - room name
+   * @param output - file or stream output
+   * @param opts - TrackCompositeOptions
    */
   async startTrackCompositeEgress(
     roomName: string,
@@ -358,6 +361,7 @@ export class EgressClient extends ServiceBase {
     return EgressInfo.fromJson(data, { ignoreUnknownFields: true });
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private isEncodedOutputs(output: any): output is EncodedOutputs {
     return (
       (<EncodedOutputs>output).file !== undefined ||
@@ -366,6 +370,7 @@ export class EgressClient extends ServiceBase {
     );
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private isEncodedFileOutput(output: any): output is EncodedFileOutput {
     return (
       (<EncodedFileOutput>output).filepath !== undefined ||
@@ -373,6 +378,7 @@ export class EgressClient extends ServiceBase {
     );
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private isSegmentedFileOutput(output: any): output is SegmentedFileOutput {
     return (
       (<SegmentedFileOutput>output).filenamePrefix !== undefined ||
@@ -381,6 +387,7 @@ export class EgressClient extends ServiceBase {
     );
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private isStreamOutput(output: any): output is StreamOutput {
     return (
       (<StreamOutput>output).protocol !== undefined || (<StreamOutput>output).urls !== undefined
@@ -489,9 +496,9 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param roomName room name
-   * @param output file or websocket output
-   * @param trackId track Id
+   * @param roomName - room name
+   * @param output - file or websocket output
+   * @param trackId - track Id
    */
   async startTrackEgress(
     roomName: string,
@@ -537,8 +544,8 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param egressId
-   * @param layout
+   * @param egressId -
+   * @param layout -
    */
   async updateLayout(egressId: string, layout: string): Promise<EgressInfo> {
     const data = await this.rpc.request(
@@ -551,9 +558,9 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param egressId
-   * @param addOutputUrls
-   * @param removeOutputUrls
+   * @param egressId -
+   * @param addOutputUrls -
+   * @param removeOutputUrls -
    */
   async updateStream(
     egressId: string,
@@ -573,17 +580,17 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param options options to filter listed Egresses, by default returns all
+   * @param options - options to filter listed Egresses, by default returns all
    * Egress instances
    */
   async listEgress(options?: ListEgressOptions): Promise<Array<EgressInfo>>;
   /**
-   * @deprecated
-   * @param roomName list egress for one room only
+   * @deprecated use `listEgress(options?: ListEgressOptions)` instead
+   * @param roomName - list egress for one room only
    */
   async listEgress(roomName?: string): Promise<Array<EgressInfo>>;
   /**
-   * @param roomName list egress for one room only
+   * @param roomName - list egress for one room only
    */
   async listEgress(options?: string | ListEgressOptions): Promise<Array<EgressInfo>> {
     let req: Partial<ListEgressRequest> = {};
@@ -603,7 +610,7 @@ export class EgressClient extends ServiceBase {
   }
 
   /**
-   * @param egressId
+   * @param egressId -
    */
   async stopEgress(egressId: string): Promise<EgressInfo> {
     const data = await this.rpc.request(

package/src/IngressClient.ts

@@ -1,19 +1,18 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import type { IngressAudioOptions, IngressInput, IngressVideoOptions } from '@livekit/protocol';
 import {
   CreateIngressRequest,
   DeleteIngressRequest,
-  IngressAudioOptions,
   IngressInfo,
-  IngressInput,
-  IngressVideoOptions,
   ListIngressRequest,
   ListIngressResponse,
   UpdateIngressRequest,
 } from '@livekit/protocol';
 import ServiceBase from './ServiceBase.js';
-import { Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
+import type { Rpc } from './TwirpRPC.js';
+import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
 
 const svc = 'Ingress';
 
@@ -122,9 +121,9 @@ export class IngressClient extends ServiceBase {
   private readonly rpc: Rpc;
 
   /**
-   * @param host hostname including protocol. i.e. 'https://cluster.livekit.io'
-   * @param apiKey API Key, can be set in env var LIVEKIT_API_KEY
-   * @param secret API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param host - hostname including protocol. i.e. 'https://cluster.livekit.io'
+   * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
+   * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
    */
   constructor(host: string, apiKey?: string, secret?: string) {
     super(apiKey, secret);
@@ -132,8 +131,8 @@ export class IngressClient extends ServiceBase {
   }
 
   /**
-   * @param inputType protocol for the ingress
-   * @param opts CreateIngressOptions
+   * @param inputType - protocol for the ingress
+   * @param opts - CreateIngressOptions
    */
   async createIngress(inputType: IngressInput, opts?: CreateIngressOptions): Promise<IngressInfo> {
     let name: string = '';
@@ -184,8 +183,8 @@ export class IngressClient extends ServiceBase {
   }
 
   /**
-   * @param ingressId ID of the ingress to update
-   * @param opts UpdateIngressOptions
+   * @param ingressId - ID of the ingress to update
+   * @param opts - UpdateIngressOptions
    */
   async updateIngress(ingressId: string, opts: UpdateIngressOptions): Promise<IngressInfo> {
     const name: string = opts.name || '';
@@ -218,14 +217,17 @@ export class IngressClient extends ServiceBase {
   }
 
   /**
-   * @deprecated use listIngress(opts) instead
-   * @param roomName list ingress for one room only
+   * @deprecated use `listIngress(opts)` or `listIngress(arg)` instead
+   * @param roomName - list ingress for one room only
    */
   async listIngress(roomName?: string): Promise<Array<IngressInfo>>;
   /**
-   * @param opts list options
+   * @param opts - list options
    */
   async listIngress(opts?: ListIngressOptions): Promise<Array<IngressInfo>>;
+  /**
+   * @param arg - list room name or options
+   */
   async listIngress(arg?: string | ListIngressOptions): Promise<Array<IngressInfo>> {
     let req: Partial<ListIngressRequest> = {};
     if (typeof arg === 'string') {
@@ -243,7 +245,7 @@ export class IngressClient extends ServiceBase {
   }
 
   /**
-   * @param ingressId ingress to delete
+   * @param ingressId - ingress to delete
    */
   async deleteIngress(ingressId: string): Promise<IngressInfo> {
     const data = await this.rpc.request(

package/src/RoomServiceClient.ts

@@ -122,7 +122,7 @@ export class RoomServiceClient extends ServiceBase {
    * Creates a new room. Explicit room creation is not required, since rooms will
    * be automatically created when the first participant joins. This method can be
    * used to customize room settings.
-   * @param options
+   * @param options -
    */
   async createRoom(options: CreateOptions): Promise<Room> {
     const data = await this.rpc.request(
@@ -162,8 +162,8 @@ export class RoomServiceClient extends ServiceBase {
 
   /**
    * Update metadata of a room
-   * @param room name of the room
-   * @param metadata the new metadata for the room
+   * @param room - name of the room
+   * @param metadata - the new metadata for the room
    */
   async updateRoomMetadata(room: string, metadata: string) {
     const data = await this.rpc.request(
@@ -177,7 +177,7 @@ export class RoomServiceClient extends ServiceBase {
 
   /**
    * List participants in a room
-   * @param room name of the room
+   * @param room - name of the room
    */
   async listParticipants(room: string): Promise<ParticipantInfo[]> {
     const data = await this.rpc.request(
@@ -193,8 +193,8 @@ export class RoomServiceClient extends ServiceBase {
   /**
    * Get information on a specific participant, including the tracks that participant
    * has published
-   * @param room name of the room
-   * @param identity identity of the participant to return
+   * @param room - name of the room
+   * @param identity - identity of the participant to return
    */
   async getParticipant(room: string, identity: string): Promise<ParticipantInfo> {
     const data = await this.rpc.request(
@@ -211,8 +211,8 @@ export class RoomServiceClient extends ServiceBase {
    * Removes a participant in the room. This will disconnect the participant
    * and will emit a Disconnected event for that participant.
    * Even after being removed, the participant can still re-join the room.
-   * @param room
-   * @param identity
+   * @param room -
+   * @param identity -
    */
   async removeParticipant(room: string, identity: string): Promise<void> {
     await this.rpc.request(
@@ -225,10 +225,10 @@ export class RoomServiceClient extends ServiceBase {
 
   /**
    * Mutes a track that the participant has published.
-   * @param room
-   * @param identity
-   * @param trackSid sid of the track to be muted
-   * @param muted true to mute, false to unmute
+   * @param room -
+   * @param identity -
+   * @param trackSid - sid of the track to be muted
+   * @param muted - true to mute, false to unmute
    */
   async mutePublishedTrack(
     room: string,
@@ -312,10 +312,10 @@ export class RoomServiceClient extends ServiceBase {
 
   /**
    * Updates a participant's subscription to tracks
-   * @param room
-   * @param identity
-   * @param trackSids
-   * @param subscribe true to subscribe, false to unsubscribe
+   * @param room -
+   * @param identity -
+   * @param trackSids -
+   * @param subscribe - true to subscribe, false to unsubscribe
    */
   async updateSubscriptions(
     room: string,
@@ -340,10 +340,10 @@ export class RoomServiceClient extends ServiceBase {
 
   /**
    * Sends data message to participants in the room
-   * @param room
-   * @param data opaque payload to send
-   * @param kind delivery reliability
-   * @param options optionally specify a topic and destinationSids (when destinationSids is empty, message is sent to everyone)
+   * @param room -
+   * @param data - opaque payload to send
+   * @param kind - delivery reliability
+   * @param options - optionally specify a topic and destinationSids (when destinationSids is empty, message is sent to everyone)
    */
   async sendData(
     room: string,
@@ -354,10 +354,10 @@ export class RoomServiceClient extends ServiceBase {
   /**
    * Sends data message to participants in the room
    * @deprecated use sendData(room, data, kind, options) instead
-   * @param room
-   * @param data opaque payload to send
-   * @param kind delivery reliability
-   * @param destinationSids optional. when empty, message is sent to everyone
+   * @param room -
+   * @param data - opaque payload to send
+   * @param kind - delivery reliability
+   * @param destinationSids - optional. when empty, message is sent to everyone
    */
   async sendData(
     room: string,

package/src/ServiceBase.ts

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { AccessToken } from './AccessToken.js';
-import { SIPGrant, VideoGrant } from './grants.js';
+import type { SIPGrant, VideoGrant } from './grants.js';
 
 /**
  * Utilities to handle authentication
@@ -15,9 +15,9 @@ export default class ServiceBase {
   private readonly ttl: string;
 
   /**
-   * @param apiKey API Key.
-   * @param secret API Secret.
-   * @param ttl token TTL
+   * @param apiKey - API Key.
+   * @param secret - API Secret.
+   * @param ttl - token TTL
    */
   constructor(apiKey?: string, secret?: string, ttl?: string) {
     this.apiKey = apiKey;
@@ -25,7 +25,7 @@ export default class ServiceBase {
     this.ttl = ttl || '10m';
   }
 
-  async authHeader(grant: VideoGrant, sip?: SIPGrant): Promise<any> {
+  async authHeader(grant: VideoGrant, sip?: SIPGrant): Promise<Record<string, string>> {
     const at = new AccessToken(this.apiKey, this.secret, { ttl: this.ttl });
     at.addGrant(grant);
     if (sip) {

package/src/SipClient.ts

@@ -26,9 +26,11 @@ import {
   SIPParticipantInfo,
   SIPTransport,
   SIPTrunkInfo,
+  TransferSIPParticipantRequest,
 } from '@livekit/protocol';
 import ServiceBase from './ServiceBase.js';
-import { Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
+import type { Rpc } from './TwirpRPC.js';
+import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
 
 const svc = 'SIP';
 
@@ -95,9 +97,9 @@ export class SipClient extends ServiceBase {
   private readonly rpc: Rpc;
 
   /**
-   * @param host hostname including protocol. i.e. 'https://cluster.livekit.io'
-   * @param apiKey API Key, can be set in env var LIVEKIT_API_KEY
-   * @param secret API Secret, can be set in env var LIVEKIT_API_SECRET
+   * @param host - hostname including protocol. i.e. 'https://cluster.livekit.io'
+   * @param apiKey - API Key, can be set in env var LIVEKIT_API_KEY
+   * @param secret - API Secret, can be set in env var LIVEKIT_API_SECRET
    */
   constructor(host: string, apiKey?: string, secret?: string) {
     super(apiKey, secret);
@@ -105,9 +107,9 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @param number phone number of the trunk
-   * @param opts CreateSipTrunkOptions
-   * @deprecated use createSipInboundTrunk or createSipOutboundTrunk
+   * @param number - phone number of the trunk
+   * @param opts - CreateSipTrunkOptions
+   * @deprecated use `createSipInboundTrunk` or `createSipOutboundTrunk`
    */
   async createSipTrunk(number: string, opts?: CreateSipTrunkOptions): Promise<SIPTrunkInfo> {
     let inboundAddresses: string[] | undefined;
@@ -155,9 +157,9 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   @param name human-readable name of the trunk
-   * @param numbers phone numbers of the trunk
-   * @param opts CreateSipTrunkOptions
+   * @param name - human-readable name of the trunk
+   * @param numbers - phone numbers of the trunk
+   * @param opts - CreateSipTrunkOptions
    */
   async createSipInboundTrunk(
     name: string,
@@ -200,10 +202,10 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @param name human-readable name of the trunk
-   * @param address hostname and port of the SIP server to dial
-   * @param numbers phone numbers of the trunk
-   * @param opts CreateSipTrunkOptions
+   * @param name - human-readable name of the trunk
+   * @param address - hostname and port of the SIP server to dial
+   * @param numbers - phone numbers of the trunk
+   * @param opts - CreateSipTrunkOptions
    */
   async createSipOutboundTrunk(
     name: string,
@@ -245,7 +247,7 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @deprecated use listSipInboundTrunk or listSipOutboundTrunk
+   * @deprecated use `listSipInboundTrunk` or `listSipOutboundTrunk`
    */
   async listSipTrunk(): Promise<Array<SIPTrunkInfo>> {
     const req: Partial<ListSIPTrunkRequest> = {};
@@ -281,7 +283,7 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @param sipTrunkId sip trunk to delete
+   * @param sipTrunkId - sip trunk to delete
    */
   async deleteSipTrunk(sipTrunkId: string): Promise<SIPTrunkInfo> {
     const data = await this.rpc.request(
@@ -294,8 +296,8 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @param rule sip dispatch rule
-   * @param opts CreateSipDispatchRuleOptions
+   * @param rule - sip dispatch rule
+   * @param opts - CreateSipDispatchRuleOptions
    */
   async createSipDispatchRule(
     rule: SipDispatchRuleDirect | SipDispatchRuleIndividual,
@@ -364,7 +366,7 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @param sipDispatchRuleId sip trunk to delete
+   * @param sipDispatchRuleId - sip trunk to delete
    */
   async deleteSipDispatchRule(sipDispatchRuleId: string): Promise<SIPDispatchRuleInfo> {
     const data = await this.rpc.request(
@@ -377,10 +379,10 @@ export class SipClient extends ServiceBase {
   }
 
   /**
-   * @param sipTrunkId sip trunk to use for the call
-   * @param number number to dial
-   * @param roomName room to attach the call to
-   * @param opts CreateSipParticipantOptions
+   * @param sipTrunkId - sip trunk to use for the call
+   * @param number - number to dial
+   * @param roomName - room to attach the call to
+   * @param opts - CreateSipParticipantOptions
    */
   async createSipParticipant(
     sipTrunkId: string,
@@ -424,4 +426,28 @@ export class SipClient extends ServiceBase {
     );
     return SIPParticipantInfo.fromJson(data, { ignoreUnknownFields: true });
   }
+
+  /**
+   * @param roomName - room the SIP participant to transfer is connectd to
+   * @param participantIdentity - identity of the SIP participant to transfer
+   * @param transferTo - SIP URL to transfer the participant to
+   */
+  async transferSipParticipant(
+    roomName: string,
+    participantIdentity: string,
+    transferTo: string,
+  ): Promise<void> {
+    const req = new TransferSIPParticipantRequest({
+      participantIdentity: participantIdentity,
+      roomName: roomName,
+      transferTo: transferTo,
+    }).toJson();
+
+    await this.rpc.request(
+      svc,
+      'TransferSIPParticipant',
+      req,
+      await this.authHeader({ roomAdmin: true, room: roomName }, { call: true }),
+    );
+  }
 }

package/src/TwirpRPC.ts

@@ -10,6 +10,7 @@ const defaultPrefix = '/twirp';
 
 export const livekitPackage = 'livekit';
 export interface Rpc {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   request(service: string, method: string, data: JsonValue, headers?: any): Promise<string>;
 }
 
@@ -32,6 +33,7 @@ export class TwirpRpc {
     this.prefix = prefix || defaultPrefix;
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async request(service: string, method: string, data: any, headers?: any): Promise<any> {
     const path = `${this.prefix}/${this.pkg}.${service}/${method}`;
     const url = new URL(path, this.host);

package/src/WebhookReceiver.ts

@@ -37,7 +37,7 @@ export type WebhookEventNames =
   | 'ingress_ended'
   /**
    * @internal
-   * @note only used as a default value, not a valid webhook event
+   * @remarks only used as a default value, not a valid webhook event
    */
   | '';
 
@@ -49,10 +49,9 @@ export class WebhookReceiver {
   }
 
   /**
-   *
-   * @param body string of the posted body
-   * @param authHeader `Authorization` header from the request
-   * @param skipAuth true to skip auth validation
+   * @param body - string of the posted body
+   * @param authHeader - `Authorization` header from the request
+   * @param skipAuth - true to skip auth validation
    * @returns
    */
   async receive(

package/src/grants.test.ts

@@ -3,7 +3,8 @@
 // SPDX-License-Identifier: Apache-2.0
 import { TrackSource } from '@livekit/protocol';
 import { describe, expect, it } from 'vitest';
-import { ClaimGrants, VideoGrant, claimsToJwtPayload } from './grants';
+import type { ClaimGrants, VideoGrant } from './grants';
+import { claimsToJwtPayload } from './grants';
 
 describe('ClaimGrants are parsed correctly', () => {
   it('parses TrackSource correctly to strings', () => {

package/src/grants.ts

@@ -22,6 +22,7 @@ export function trackSourceToString(source: TrackSource) {
 export function claimsToJwtPayload(
   grant: ClaimGrants,
 ): JWTPayload & { video?: Record<string, unknown> } {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const claim: Record<string, any> = { ...grant };
   // eslint-disable-next-line no-restricted-syntax
   if (Array.isArray(claim.video?.canPublishSources)) {

package/src/index.ts

@@ -16,6 +16,8 @@ export {
   EncodingOptions,
   EncodingOptionsPreset,
   GCPUpload,
+  ImageCodec,
+  ImageFileSuffix,
   ImageOutput,
   IngressAudioEncodingOptions,
   IngressAudioEncodingPreset,
@@ -50,8 +52,8 @@ export {
 } from '@livekit/protocol';
 export * from './AccessToken.js';
 export * from './EgressClient.js';
+export * from './grants.js';
 export * from './IngressClient.js';
 export * from './RoomServiceClient.js';
 export * from './SipClient.js';
 export * from './WebhookReceiver.js';
-export * from './grants.js';