livekit-server-sdk 2.13.3 → 2.14.1

package/src/AgentDispatchClient.ts

@@ -8,6 +8,7 @@ import {
   ListAgentDispatchRequest,
   ListAgentDispatchResponse,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import { type Rpc, TwirpRpc, livekitPackage } from './TwirpRPC.js';
 
@@ -29,10 +30,14 @@ export class AgentDispatchClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @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 options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

package/src/ClientOptions.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Options common to all clients
+ */
+export type ClientOptions = {
+  /**
+   * Optional timeout, in seconds, for all server requests
+   */
+  requestTimeout?: number;
+};

package/src/EgressClient.ts

@@ -25,6 +25,7 @@ import {
   UpdateStreamRequest,
   WebEgressRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -137,10 +138,14 @@ export class EgressClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @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 options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

package/src/IngressClient.ts

@@ -10,6 +10,7 @@ import {
   ListIngressResponse,
   UpdateIngressRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -124,10 +125,14 @@ export class IngressClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @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 options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

package/src/RoomServiceClient.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import type { DataPacket_Kind, RoomEgress, TrackInfo } from '@livekit/protocol';
+import type { DataPacket_Kind, RoomAgentDispatch, RoomEgress, TrackInfo } from '@livekit/protocol';
 import {
   CreateRoomRequest,
   DeleteRoomRequest,
@@ -22,6 +22,7 @@ import {
   UpdateRoomMetadataRequest,
   UpdateSubscriptionsRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -79,6 +80,11 @@ export interface CreateOptions {
    */
   syncStreams?: boolean;
 
+  /**
+   * agents that should be dispatched to this room
+   */
+  agents?: RoomAgentDispatch[];
+
   /**
    * override the node room is allocated to, for debugging
    * does not work with Cloud
@@ -115,10 +121,14 @@ export class RoomServiceClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @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 options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**

package/src/SipClient.ts

@@ -29,6 +29,7 @@ import {
   SIPDispatchRuleIndividual,
   SIPDispatchRuleInfo,
   SIPInboundTrunkInfo,
+  SIPOutboundConfig,
   SIPOutboundTrunkInfo,
   SIPParticipantInfo,
   SIPTransport,
@@ -38,6 +39,7 @@ import {
   UpdateSIPInboundTrunkRequest,
   UpdateSIPOutboundTrunkRequest,
 } from '@livekit/protocol';
+import type { ClientOptions } from './ClientOptions.js';
 import { ServiceBase } from './ServiceBase.js';
 import type { Rpc } from './TwirpRPC.js';
 import { TwirpRpc, livekitPackage } from './TwirpRPC.js';
@@ -123,6 +125,8 @@ export interface CreateSipParticipantOptions {
   participantIdentity?: string;
   /** Optional name of the participant */
   participantName?: string;
+  /** Optional display name for the SIP participant */
+  displayName?: string;
   /** Optional metadata to attach to the participant */
   participantMetadata?: string;
   /** Optional attributes to attach to the participant */
@@ -213,10 +217,14 @@ export class SipClient extends ServiceBase {
    * @param host - hostname including protocol. i.e. 'https://<project>.livekit.cloud'
    * @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 options - client options
    */
-  constructor(host: string, apiKey?: string, secret?: string) {
+  constructor(host: string, apiKey?: string, secret?: string, options?: ClientOptions) {
     super(apiKey, secret);
-    this.rpc = new TwirpRpc(host, livekitPackage);
+    const rpcOptions = options?.requestTimeout
+      ? { requestTimeout: options.requestTimeout }
+      : undefined;
+    this.rpc = new TwirpRpc(host, livekitPackage, rpcOptions);
   }
 
   /**
@@ -696,6 +704,7 @@ export class SipClient extends ServiceBase {
    * @param number - number to dial
    * @param roomName - room to attach the call to
    * @param opts - CreateSipParticipantOptions
+   * @param outboundTrunkConfig - Optional outbound trunk configuration for sip participant.
    * @returns Created SIP participant
    */
   async createSipParticipant(
@@ -703,6 +712,7 @@ export class SipClient extends ServiceBase {
     number: string,
     roomName: string,
     opts?: CreateSipParticipantOptions,
+    outboundTrunkConfig?: SIPOutboundConfig,
   ): Promise<SIPParticipantInfo> {
     if (opts === undefined) {
       opts = {};
@@ -714,11 +724,13 @@ export class SipClient extends ServiceBase {
 
     const req = new CreateSIPParticipantRequest({
       sipTrunkId: sipTrunkId,
+      trunk: outboundTrunkConfig,
       sipCallTo: number,
       sipNumber: opts.fromNumber,
       roomName: roomName,
       participantIdentity: opts.participantIdentity || 'sip-participant',
       participantName: opts.participantName,
+      displayName: opts.displayName,
       participantMetadata: opts.participantMetadata,
       participantAttributes: opts.participantAttributes,
       dtmf: opts.dtmf,

package/src/TwirpRPC.ts

@@ -5,7 +5,15 @@ import type { JsonValue } from '@bufbuild/protobuf';
 
 // twirp RPC adapter for client implementation
 
+type Options = {
+  /** Prefix for the RPC requests */
+  prefix?: string;
+  /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */
+  requestTimeout?: number;
+};
+
 const defaultPrefix = '/twirp';
+const defaultTimeoutSeconds = 60;
 
 export const livekitPackage = 'livekit';
 export interface Rpc {
@@ -48,13 +56,16 @@ export class TwirpRpc {
 
   prefix: string;
 
-  constructor(host: string, pkg: string, prefix?: string) {
+  requestTimeout: number;
+
+  constructor(host: string, pkg: string, options?: Options) {
     if (host.startsWith('ws')) {
       host = host.replace('ws', 'http');
     }
     this.host = host;
     this.pkg = pkg;
-    this.prefix = prefix || defaultPrefix;
+    this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;
+    this.prefix = options?.prefix || defaultPrefix;
   }
 
   async request(
@@ -62,7 +73,7 @@ export class TwirpRpc {
     method: string,
     data: any, // eslint-disable-line @typescript-eslint/no-explicit-any
     headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any
-    timeout = 60,
+    timeout = this.requestTimeout,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): Promise<any> {
     const path = `${this.prefix}/${this.pkg}.${service}/${method}`;

package/src/grants.test.ts

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { TrackSource } from '@livekit/protocol';
 import { describe, expect, it } from 'vitest';
-import type { ClaimGrants, VideoGrant } from './grants.js';
+import type { ClaimGrants, ObservabilityGrant, VideoGrant } from './grants.js';
 import { claimsToJwtPayload } from './grants.js';
 
 describe('ClaimGrants are parsed correctly', () => {
@@ -28,4 +28,16 @@ describe('ClaimGrants are parsed correctly', () => {
       'screen_share_audio',
     ]);
   });
+
+  it('parses ObservabilityGrant correctly', () => {
+    const grant: ObservabilityGrant = {
+      write: true,
+    };
+
+    const claim: ClaimGrants = { observability: grant };
+
+    const jwtPayload = claimsToJwtPayload(claim);
+    expect(jwtPayload.observability).toBeTypeOf('object');
+    expect((jwtPayload.observability as ObservabilityGrant)?.write).toBe(true);
+  });
 });

package/src/grants.ts

@@ -108,12 +108,18 @@ export interface InferenceGrant {
   perform?: boolean;
 }
 
+export interface ObservabilityGrant {
+  /** write grants to publish observability data */
+  write?: boolean;
+}
+
 /** @internal */
 export interface ClaimGrants extends JWTPayload {
   name?: string;
   video?: VideoGrant;
   sip?: SIPGrant;
   inference?: InferenceGrant;
+  observability?: ObservabilityGrant;
   kind?: string;
   metadata?: string;
   attributes?: Record<string, string>;

package/src/index.ts

@@ -34,6 +34,7 @@ export {
   ParticipantInfo_State,
   ParticipantPermission,
   Room,
+  RoomAgentDispatch,
   RoomCompositeEgressRequest,
   RoomEgress,
   S3Upload,