livekit-client 2.15.16 → 2.16.1

package/src/room/errors.ts

@@ -10,6 +10,14 @@ export class LivekitError extends Error {
   }
 }
 
+export class SimulatedError extends LivekitError {
+  readonly name = 'simulated';
+
+  constructor(message = 'Simulated failure') {
+    super(-1, message);
+  }
+}
+
 export enum ConnectionErrorReason {
   NotAllowed,
   ServerUnreachable,
@@ -17,80 +25,189 @@ export enum ConnectionErrorReason {
   Cancelled,
   LeaveRequest,
   Timeout,
+  WebSocket,
 }
 
-export class ConnectionError extends LivekitError {
+type NotAllowed = {
+  reason: ConnectionErrorReason.NotAllowed;
+  status: number;
+  context?: unknown;
+};
+
+type InternalError = {
+  reason: ConnectionErrorReason.InternalError;
+  status: never;
+  context?: { status?: number; statusText?: string };
+};
+
+type ConnectionTimeout = {
+  reason: ConnectionErrorReason.Timeout;
+  status: never;
+  context: never;
+};
+
+type LeaveRequest = {
+  reason: ConnectionErrorReason.LeaveRequest;
+  status: never;
+  context: DisconnectReason;
+};
+
+type Cancelled = {
+  reason: ConnectionErrorReason.Cancelled;
+  status: never;
+  context: never;
+};
+
+type ServerUnreachable = {
+  reason: ConnectionErrorReason.ServerUnreachable;
+  status?: number;
+  context?: never;
+};
+
+type WebSocket = {
+  reason: ConnectionErrorReason.WebSocket;
   status?: number;
+  context?: string;
+};
+
+type ConnectionErrorVariants =
+  | NotAllowed
+  | ConnectionTimeout
+  | LeaveRequest
+  | InternalError
+  | Cancelled
+  | ServerUnreachable
+  | WebSocket;
 
-  context?: unknown | DisconnectReason;
+export class ConnectionError<
+  Variant extends ConnectionErrorVariants = ConnectionErrorVariants,
+> extends LivekitError {
+  status?: Variant['status'];
 
-  reason: ConnectionErrorReason;
+  context: Variant['context'];
+
+  reason: Variant['reason'];
 
   reasonName: string;
 
-  constructor(
+  readonly name = 'ConnectionError';
+
+  protected constructor(
     message: string,
-    reason: ConnectionErrorReason,
-    status?: number,
-    context?: unknown | DisconnectReason,
+    reason: Variant['reason'],
+    status?: Variant['status'],
+    context?: Variant['context'],
   ) {
     super(1, message);
-    this.name = 'ConnectionError';
     this.status = status;
     this.reason = reason;
     this.context = context;
     this.reasonName = ConnectionErrorReason[reason];
   }
+
+  static notAllowed(message: string, status: number, context?: unknown) {
+    return new ConnectionError<NotAllowed>(
+      message,
+      ConnectionErrorReason.NotAllowed,
+      status,
+      context,
+    );
+  }
+
+  static timeout(message: string) {
+    return new ConnectionError<ConnectionTimeout>(message, ConnectionErrorReason.Timeout);
+  }
+
+  static leaveRequest(message: string, context: DisconnectReason) {
+    return new ConnectionError<LeaveRequest>(
+      message,
+      ConnectionErrorReason.LeaveRequest,
+      undefined,
+      context,
+    );
+  }
+
+  static internal(message: string, context?: { status?: number; statusText?: string }) {
+    return new ConnectionError<InternalError>(
+      message,
+      ConnectionErrorReason.InternalError,
+      undefined,
+      context,
+    );
+  }
+
+  static cancelled(message: string) {
+    return new ConnectionError<Cancelled>(message, ConnectionErrorReason.Cancelled);
+  }
+
+  static serverUnreachable(message: string, status?: number) {
+    return new ConnectionError<ServerUnreachable>(
+      message,
+      ConnectionErrorReason.ServerUnreachable,
+      status,
+    );
+  }
+
+  static websocket(message: string, status?: number, reason?: string) {
+    return new ConnectionError<WebSocket>(message, ConnectionErrorReason.WebSocket, status, reason);
+  }
 }
 
 export class DeviceUnsupportedError extends LivekitError {
+  readonly name = 'DeviceUnsupportedError';
+
   constructor(message?: string) {
     super(21, message ?? 'device is unsupported');
-    this.name = 'DeviceUnsupportedError';
   }
 }
 
 export class TrackInvalidError extends LivekitError {
+  readonly name = 'TrackInvalidError';
+
   constructor(message?: string) {
     super(20, message ?? 'track is invalid');
-    this.name = 'TrackInvalidError';
   }
 }
 
 export class UnsupportedServer extends LivekitError {
+  readonly name = 'UnsupportedServer';
+
   constructor(message?: string) {
     super(10, message ?? 'unsupported server');
-    this.name = 'UnsupportedServer';
   }
 }
 
 export class UnexpectedConnectionState extends LivekitError {
+  readonly name = 'UnexpectedConnectionState';
+
   constructor(message?: string) {
     super(12, message ?? 'unexpected connection state');
-    this.name = 'UnexpectedConnectionState';
   }
 }
 
 export class NegotiationError extends LivekitError {
+  readonly name = 'NegotiationError';
+
   constructor(message?: string) {
     super(13, message ?? 'unable to negotiate');
-    this.name = 'NegotiationError';
   }
 }
 
 export class PublishDataError extends LivekitError {
+  readonly name = 'PublishDataError';
+
   constructor(message?: string) {
     super(14, message ?? 'unable to publish data');
-    this.name = 'PublishDataError';
   }
 }
 
 export class PublishTrackError extends LivekitError {
+  readonly name = 'PublishTrackError';
+
   status: number;
 
   constructor(message: string, status: number) {
     super(15, message);
-    this.name = 'PublishTrackError';
     this.status = status;
   }
 }
@@ -100,6 +217,8 @@ export type RequestErrorReason =
   | 'TimeoutError';
 
 export class SignalRequestError extends LivekitError {
+  readonly name = 'SignalRequestError';
+
   reason: RequestErrorReason;
 
   reasonName: string;
@@ -136,18 +255,27 @@ export enum DataStreamErrorReason {
 }
 
 export class DataStreamError extends LivekitError {
+  readonly name = 'DataStreamError';
+
   reason: DataStreamErrorReason;
 
   reasonName: string;
 
   constructor(message: string, reason: DataStreamErrorReason) {
     super(16, message);
-    this.name = 'DataStreamError';
     this.reason = reason;
     this.reasonName = DataStreamErrorReason[reason];
   }
 }
 
+export class SignalReconnectError extends LivekitError {
+  readonly name = 'SignalReconnectError';
+
+  constructor(message?: string) {
+    super(18, message);
+  }
+}
+
 export enum MediaDeviceFailure {
   // user rejected permissions
   PermissionDenied = 'PermissionDenied',

package/src/room/participant/LocalParticipant.ts

@@ -137,11 +137,11 @@ export default class LocalParticipant extends Participant {
 
   private encryptionType: Encryption_Type = Encryption_Type.NONE;
 
-  private reconnectFuture?: Future<void>;
+  private reconnectFuture?: Future<void, Error>;
 
-  private signalConnectedFuture?: Future<void>;
+  private signalConnectedFuture?: Future<void, Error>;
 
-  private activeAgentFuture?: Future<RemoteParticipant>;
+  private activeAgentFuture?: Future<RemoteParticipant, Error>;
 
   private firstActiveAgent?: RemoteParticipant;
 
@@ -262,7 +262,7 @@ export default class LocalParticipant extends Participant {
 
   private handleReconnecting = () => {
     if (!this.reconnectFuture) {
-      this.reconnectFuture = new Future<void>();
+      this.reconnectFuture = new Future<void, Error>();
     }
   };
 
@@ -275,15 +275,15 @@ export default class LocalParticipant extends Participant {
   private handleClosing = () => {
     if (this.reconnectFuture) {
       this.reconnectFuture.promise.catch((e) => this.log.warn(e.message, this.logContext));
-      this.reconnectFuture?.reject?.('Got disconnected during reconnection attempt');
+      this.reconnectFuture?.reject?.(new Error('Got disconnected during reconnection attempt'));
       this.reconnectFuture = undefined;
     }
     if (this.signalConnectedFuture) {
-      this.signalConnectedFuture.reject?.('Got disconnected without signal connected');
+      this.signalConnectedFuture.reject?.(new Error('Got disconnected without signal connected'));
       this.signalConnectedFuture = undefined;
     }
 
-    this.activeAgentFuture?.reject?.('Got disconnected without active agent present');
+    this.activeAgentFuture?.reject?.(new Error('Got disconnected without active agent present'));
     this.activeAgentFuture = undefined;
     this.firstActiveAgent = undefined;
   };
@@ -293,7 +293,7 @@ export default class LocalParticipant extends Participant {
       this.updateInfo(joinResponse.participant);
     }
     if (!this.signalConnectedFuture) {
-      this.signalConnectedFuture = new Future<void>();
+      this.signalConnectedFuture = new Future<void, Error>();
     }
 
     this.signalConnectedFuture.resolve?.();
@@ -926,7 +926,7 @@ export default class LocalParticipant extends Participant {
 
   private waitUntilEngineConnected() {
     if (!this.signalConnectedFuture) {
-      this.signalConnectedFuture = new Future<void>();
+      this.signalConnectedFuture = new Future<void, Error>();
     }
     return this.signalConnectedFuture.promise;
   }
@@ -1824,7 +1824,7 @@ export default class LocalParticipant extends Participant {
         resolve: (responsePayload: string | null, responseError: RpcError | null) => {
           clearTimeout(responseTimeoutId);
           if (this.pendingAcks.has(id)) {
-            console.warn('RPC response received before ack', id);
+            this.log.warn('RPC response received before ack', id);
             this.pendingAcks.delete(id);
             clearTimeout(ackTimeoutId);
           }
@@ -2009,7 +2009,7 @@ export default class LocalParticipant extends Participant {
     if (agent) {
       this.activeAgentFuture?.resolve?.(agent);
     } else {
-      this.activeAgentFuture?.reject?.('Agent disconnected');
+      this.activeAgentFuture?.reject?.(new Error('Agent disconnected'));
     }
     this.activeAgentFuture = undefined;
   }
@@ -2019,7 +2019,7 @@ export default class LocalParticipant extends Participant {
       return Promise.resolve(this.firstActiveAgent);
     }
     if (!this.activeAgentFuture) {
-      this.activeAgentFuture = new Future<RemoteParticipant>();
+      this.activeAgentFuture = new Future<RemoteParticipant, Error>();
     }
     return this.activeAgentFuture.promise;
   }

package/src/room/participant/Participant.ts

@@ -96,7 +96,7 @@ export default class Participant extends (EventEmitter as new () => TypedEmitter
 
   protected loggerOptions?: LoggerOptions;
 
-  protected activeFuture?: Future<void>;
+  protected activeFuture?: Future<void, Error>;
 
   protected get logContext() {
     return {
@@ -195,7 +195,7 @@ export default class Participant extends (EventEmitter as new () => TypedEmitter
       return this.activeFuture.promise;
     }
 
-    this.activeFuture = new Future<void>();
+    this.activeFuture = new Future<void, Error>();
 
     this.once(ParticipantEvent.Active, () => {
       this.activeFuture?.resolve?.();

package/src/room/token-source/TokenSource.ts

@@ -245,9 +245,13 @@ class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
 }
 
 export {
+  /** The return type of {@link TokenSource.literal} */
   type TokenSourceLiteral,
+  /** The return type of {@link TokenSource.custom} */
   type TokenSourceCustom,
+  /** The return type of {@link TokenSource.endpoint} */
   type TokenSourceEndpoint,
+  /** The return type of {@link TokenSource.sandboxTokenServer} */
   type TokenSourceSandboxTokenServer,
   decodeTokenPayload,
   areTokenSourceFetchOptionsEqual,
@@ -273,7 +277,7 @@ export const TokenSource = {
   /**
    * TokenSource.endpoint creates a token source that fetches credentials from a given URL using
    * the standard endpoint format:
-   * FIXME: add docs link here in the future!
+   * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
    */
   endpoint(url: string, options: EndpointOptions = {}) {
     return new TokenSourceEndpoint(url, options);

package/src/room/track/LocalTrack.ts

@@ -518,8 +518,6 @@ export default abstract class LocalTrack<
    * Sets a processor on this track.
    * See https://github.com/livekit/track-processors-js for example usage
    *
-   * @experimental
-   *
    * @param processor
    * @param showProcessedStreamLocally
    * @returns
@@ -592,8 +590,6 @@ export default abstract class LocalTrack<
    * Stops the track processor
    * See https://github.com/livekit/track-processors-js for example usage
    *
-   * @experimental
-   * @returns
    */
   async stopProcessor(keepElement = true) {
     const unlock = await this.trackChangeLock.lock();

package/src/room/track/TrackPublication.ts

@@ -1,11 +1,11 @@
 import { Encryption_Type } from '@livekit/protocol';
+import { EventEmitter } from 'events';
 import type {
   SubscriptionError,
   TrackInfo,
   UpdateSubscription,
   UpdateTrackSettings,
 } from '@livekit/protocol';
-import { EventEmitter } from 'events';
 import type TypedEventEmitter from 'typed-emitter';
 import log, { LoggerNames, getLogger } from '../../logger';
 import { TrackEvent } from '../events';

package/src/room/track/create.ts

@@ -78,11 +78,13 @@ export async function createLocalTracks(
       deviceId: { ideal: deviceId },
     };
   }
-  if (
-    internalOptions.audio === true ||
-    (typeof internalOptions.audio === 'object' && !internalOptions.audio.deviceId)
-  ) {
+  if (internalOptions.audio === true) {
     internalOptions.audio = { deviceId: 'default' };
+  } else if (typeof internalOptions.audio === 'object' && internalOptions.audio !== null) {
+    internalOptions.audio = {
+      ...internalOptions.audio,
+      deviceId: internalOptions.audio.deviceId || 'default',
+    };
   }
   if (internalOptions.video === true) {
     internalOptions.video = { deviceId: 'default' };

package/src/room/track/processor/types.ts

@@ -11,9 +11,6 @@ export type ProcessorOptions<T extends Track.Kind> = {
   audioContext?: AudioContext;
 };
 
-/**
- * @experimental
- */
 export interface AudioProcessorOptions extends ProcessorOptions<Track.Kind.Audio> {
   audioContext: AudioContext;
 }
@@ -23,9 +20,6 @@ export interface AudioProcessorOptions extends ProcessorOptions<Track.Kind.Audio
  */
 export interface VideoProcessorOptions extends ProcessorOptions<Track.Kind.Video> {}
 
-/**
- * @experimental
- */
 export interface TrackProcessor<
   T extends Track.Kind,
   U extends ProcessorOptions<T> = ProcessorOptions<T>,

package/src/room/types.ts

@@ -125,7 +125,7 @@ export interface StreamController<T extends DataStream_Chunk> {
   startTime: number;
   endTime?: number;
   sendingParticipantIdentity: string;
-  outOfBandFailureRejectingFuture: Future<never>;
+  outOfBandFailureRejectingFuture: Future<never, Error>;
 }
 
 export interface BaseStreamInfo {

package/src/room/utils.ts

@@ -5,7 +5,8 @@ import {
   DisconnectReason,
   Transcription as TranscriptionModel,
 } from '@livekit/protocol';
-import { type BrowserDetails, getBrowser } from '../utils/browserParser';
+import { getBrowser } from '../utils/browserParser';
+import type { BrowserDetails } from '../utils/browserParser';
 import { protocolVersion, version } from '../version';
 import { type ConnectionError, ConnectionErrorReason } from './errors';
 import type LocalParticipant from './participant/LocalParticipant';
@@ -455,12 +456,12 @@ export function getStereoAudioStreamTrack() {
   return stereoTrack;
 }
 
-export class Future<T> {
+export class Future<T, E extends Error> {
   promise: Promise<T>;
 
   resolve?: (arg: T) => void;
 
-  reject?: (e: any) => void;
+  reject?: (e: E) => void;
 
   onFinally?: () => void;
 
@@ -471,7 +472,7 @@ export class Future<T> {
   private _isResolved: boolean = false;
 
   constructor(
-    futureBase?: (resolve: (arg: T) => void, reject: (e: any) => void) => void,
+    futureBase?: (resolve: (arg: T) => void, reject: (e: E) => void) => void,
     onFinally?: () => void,
   ) {
     this.onFinally = onFinally;

package/src/test/mocks.ts

@@ -1,4 +1,3 @@
-// eslint-disable-next-line import/no-extraneous-dependencies
 import { type MockedClass, vi } from 'vitest';
 import { SignalClient } from '../api/SignalClient';
 import RTCEngine from '../room/RTCEngine';