livekit-client 2.16.0 → 2.16.1

package/dist/ts4.2/room/errors.d.ts

@@ -3,45 +3,108 @@ export declare class LivekitError extends Error {
     code: number;
     constructor(code: number, message?: string);
 }
+export declare class SimulatedError extends LivekitError {
+    readonly name = "simulated";
+    constructor(message?: string);
+}
 export declare enum ConnectionErrorReason {
     NotAllowed = 0,
     ServerUnreachable = 1,
     InternalError = 2,
     Cancelled = 3,
     LeaveRequest = 4,
-    Timeout = 5
+    Timeout = 5,
+    WebSocket = 6
 }
-export declare 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?: unknown | DisconnectReason;
-    reason: ConnectionErrorReason;
+    context?: never;
+};
+type WebSocket = {
+    reason: ConnectionErrorReason.WebSocket;
+    status?: number;
+    context?: string;
+};
+type ConnectionErrorVariants = NotAllowed | ConnectionTimeout | LeaveRequest | InternalError | Cancelled | ServerUnreachable | WebSocket;
+export declare class ConnectionError<Variant extends ConnectionErrorVariants = ConnectionErrorVariants> extends LivekitError {
+    status?: Variant['status'];
+    context: Variant['context'];
+    reason: Variant['reason'];
     reasonName: string;
-    constructor(message: string, reason: ConnectionErrorReason, status?: number, context?: unknown | DisconnectReason);
+    readonly name = "ConnectionError";
+    protected constructor(message: string, reason: Variant['reason'], status?: Variant['status'], context?: Variant['context']);
+    static notAllowed(message: string, status: number, context?: unknown): ConnectionError<NotAllowed>;
+    static timeout(message: string): ConnectionError<ConnectionTimeout>;
+    static leaveRequest(message: string, context: DisconnectReason): ConnectionError<LeaveRequest>;
+    static internal(message: string, context?: {
+        status?: number;
+        statusText?: string;
+    }): ConnectionError<InternalError>;
+    static cancelled(message: string): ConnectionError<Cancelled>;
+    static serverUnreachable(message: string, status?: number): ConnectionError<ServerUnreachable>;
+    static websocket(message: string, status?: number, reason?: string): ConnectionError<WebSocket>;
 }
 export declare class DeviceUnsupportedError extends LivekitError {
+    readonly name = "DeviceUnsupportedError";
     constructor(message?: string);
 }
 export declare class TrackInvalidError extends LivekitError {
+    readonly name = "TrackInvalidError";
     constructor(message?: string);
 }
 export declare class UnsupportedServer extends LivekitError {
+    readonly name = "UnsupportedServer";
     constructor(message?: string);
 }
 export declare class UnexpectedConnectionState extends LivekitError {
+    readonly name = "UnexpectedConnectionState";
     constructor(message?: string);
 }
 export declare class NegotiationError extends LivekitError {
+    readonly name = "NegotiationError";
     constructor(message?: string);
 }
 export declare class PublishDataError extends LivekitError {
+    readonly name = "PublishDataError";
     constructor(message?: string);
 }
 export declare class PublishTrackError extends LivekitError {
+    readonly name = "PublishTrackError";
     status: number;
     constructor(message: string, status: number);
 }
 export type RequestErrorReason = Exclude<RequestResponse_Reason, RequestResponse_Reason.OK> | 'TimeoutError';
 export declare class SignalRequestError extends LivekitError {
+    readonly name = "SignalRequestError";
     reason: RequestErrorReason;
     reasonName: string;
     constructor(message: string, reason: RequestErrorReason);
@@ -56,10 +119,15 @@ export declare enum DataStreamErrorReason {
     EncryptionTypeMismatch = 8
 }
 export declare class DataStreamError extends LivekitError {
+    readonly name = "DataStreamError";
     reason: DataStreamErrorReason;
     reasonName: string;
     constructor(message: string, reason: DataStreamErrorReason);
 }
+export declare class SignalReconnectError extends LivekitError {
+    readonly name = "SignalReconnectError";
+    constructor(message?: string);
+}
 export declare enum MediaDeviceFailure {
     PermissionDenied = "PermissionDenied",
     NotFound = "NotFound",
@@ -69,4 +137,5 @@ export declare enum MediaDeviceFailure {
 export declare namespace MediaDeviceFailure {
     function getFailure(error: any): MediaDeviceFailure | undefined;
 }
+export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/ts4.2/room/token-source/TokenSource.d.ts

@@ -56,7 +56,7 @@ export declare 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): TokenSourceEndpoint;
     /**

package/dist/ts4.2/room/track/LocalTrack.d.ts

@@ -87,8 +87,6 @@ export default abstract class LocalTrack<TrackKind extends Track.Kind = Track.Ki
      * Sets a processor on this track.
      * See https://github.com/livekit/track-processors-js for example usage
      *
-     * @experimental
-     *
      * @param processor
      * @param showProcessedStreamLocally
      * @returns
@@ -99,8 +97,6 @@ export default abstract class LocalTrack<TrackKind extends Track.Kind = Track.Ki
      * Stops the track processor
      * See https://github.com/livekit/track-processors-js for example usage
      *
-     * @experimental
-     * @returns
      */
     stopProcessor(keepElement?: boolean): Promise<void>;
     /**

package/dist/ts4.2/room/track/processor/types.d.ts

@@ -9,9 +9,6 @@ export type ProcessorOptions<T extends Track.Kind> = {
     element?: HTMLMediaElement;
     audioContext?: AudioContext;
 };
-/**
- * @experimental
- */
 export interface AudioProcessorOptions extends ProcessorOptions<Track.Kind.Audio> {
     audioContext: AudioContext;
 }
@@ -20,9 +17,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>> {
     name: string;
     init: (opts: U) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-client",
-  "version": "2.16.0",
+  "version": "2.16.1",
   "description": "JavaScript/TypeScript client SDK for LiveKit",
   "main": "./dist/livekit-client.umd.js",
   "unpkg": "./dist/livekit-client.umd.js",
@@ -55,6 +55,7 @@
     "@babel/preset-env": "7.28.5",
     "@bufbuild/protoc-gen-es": "^1.10.0",
     "@changesets/cli": "2.29.7",
+    "@eslint/js": "9.39.1",
     "@livekit/changesets-changelog-github": "^0.0.4",
     "@rollup/plugin-babel": "6.1.0",
     "@rollup/plugin-commonjs": "28.0.9",
@@ -63,6 +64,7 @@
     "@rollup/plugin-terser": "^0.4.4",
     "@size-limit/file": "^11.2.0",
     "@size-limit/webpack": "^11.2.0",
+    "@stylistic/eslint-plugin": "^3.1.0",
     "@trivago/prettier-plugin-sort-imports": "^5.0.0",
     "@types/events": "^3.0.3",
     "@types/sdp-transform": "2.15.0",
@@ -70,11 +72,12 @@
     "@typescript-eslint/eslint-plugin": "7.18.0",
     "@typescript-eslint/parser": "7.18.0",
     "downlevel-dts": "^0.11.0",
-    "eslint": "8.57.1",
-    "eslint-config-airbnb-typescript": "18.0.0",
+    "eslint": "9.39.1",
+    "eslint-config-airbnb-extended": "^2.3.2",
     "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-ecmascript-compat": "^3.2.1",
-    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-compat": "^6.0.2",
+    "eslint-plugin-import-x": "^4.16.1",
+    "eslint-plugin-prettier": "^5.5.4",
     "gh-pages": "6.3.0",
     "happy-dom": "^17.2.0",
     "jsdom": "^26.1.0",
@@ -86,6 +89,7 @@
     "typedoc": "0.28.14",
     "typedoc-plugin-no-inherit": "1.6.1",
     "typescript": "5.8.3",
+    "typescript-eslint": "^8.47.0",
     "vite": "7.2.2",
     "vitest": "^3.0.0"
   },
@@ -105,7 +109,7 @@
     "format:check": "prettier --check src examples/**/*.ts",
     "ci:publish": "pnpm build:clean && pnpm compat && changeset publish",
     "downlevel-dts": "downlevel-dts ./dist/src ./dist/ts4.2 --to=4.2",
-    "compat": "eslint --no-eslintrc --config ./.eslintrc.dist.cjs ./dist/livekit-client.umd.js",
+    "compat": "eslint --config ./eslint.config.dist.mjs --no-inline-config  ./dist/livekit-client.esm.mjs",
     "size-limit": "size-limit"
   }
 }

package/src/api/SignalClient.test.ts

@@ -1,4 +1,5 @@
 import {
+  DisconnectReason,
   JoinResponse,
   LeaveRequest,
   ReconnectResponse,
@@ -177,9 +178,12 @@ describe('SignalClient.connect', () => {
         websocketTimeout: 100,
       };
 
-      await expect(
-        signalClient.join('wss://test.livekit.io', 'test-token', shortTimeoutOptions),
-      ).rejects.toThrow(ConnectionError);
+      const error = await signalClient
+        .join('wss://test.livekit.io', 'test-token', shortTimeoutOptions)
+        .catch((e) => e);
+
+      expect(error).toBeInstanceOf(ConnectionError);
+      expect(error.reason).toBe(ConnectionErrorReason.Cancelled);
     });
   });
 
@@ -333,11 +337,7 @@ describe('SignalClient.connect', () => {
     });
 
     it('should handle ConnectionError from WebSocket rejection', async () => {
-      const customError = new ConnectionError(
-        'Custom error',
-        ConnectionErrorReason.InternalError,
-        500,
-      );
+      const customError = ConnectionError.internal('Custom error', { status: 500 });
 
       mockWebSocketStream({
         opened: Promise.reject(customError),
@@ -393,11 +393,9 @@ describe('SignalClient.connect', () => {
       await expect(
         signalClient.join('wss://test.livekit.io', 'test-token', defaultOptions),
       ).rejects.toMatchObject(
-        new ConnectionError(
+        ConnectionError.leaveRequest(
           'Received leave request while trying to (re)connect',
-          ConnectionErrorReason.LeaveRequest,
-          undefined,
-          1,
+          DisconnectReason.CLIENT_INITIATED,
         ),
       );
     });
@@ -700,11 +698,7 @@ describe('SignalClient.handleConnectionError', () => {
   });
 
   it('should return ConnectionError as-is if it is already a ConnectionError', async () => {
-    const connectionError = new ConnectionError(
-      'Custom error',
-      ConnectionErrorReason.InternalError,
-      500,
-    );
+    const connectionError = ConnectionError.internal('Custom error');
 
     (global.fetch as any).mockResolvedValueOnce({
       status: 500,
@@ -737,7 +731,6 @@ describe('SignalClient.handleConnectionError', () => {
 
       expect(result).toBeInstanceOf(ConnectionError);
       expect(result.reason).toBe(ConnectionErrorReason.InternalError);
-      expect(result.status).toBe(500);
     }
   });
 
@@ -755,7 +748,7 @@ describe('SignalClient.handleConnectionError', () => {
   });
 
   it('should handle fetch throwing ConnectionError', async () => {
-    const fetchError = new ConnectionError('Fetch failed', ConnectionErrorReason.ServerUnreachable);
+    const fetchError = ConnectionError.serverUnreachable('Fetch failed');
     (global.fetch as any).mockRejectedValueOnce(fetchError);
 
     const handleMethod = (signalClient as any).handleConnectionError;

package/src/api/SignalClient.ts

@@ -45,7 +45,7 @@ import {
   protoInt64,
 } from '@livekit/protocol';
 import log, { LoggerNames, getLogger } from '../logger';
-import { ConnectionError, ConnectionErrorReason } from '../room/errors';
+import { ConnectionError } from '../room/errors';
 import CriticalTimers from '../room/timers';
 import type { LoggerOptions } from '../room/types';
 import { getClientInfo, isReactNative, sleep } from '../room/utils';
@@ -319,7 +319,7 @@ export class SignalClient {
             this.close();
           }
           cleanupAbortHandlers();
-          reject(target instanceof AbortSignal ? target.reason : target);
+          reject(ConnectionError.cancelled(reason));
         };
 
         abortSignal?.addEventListener('abort', abortHandler);
@@ -330,12 +330,7 @@ export class SignalClient {
         };
 
         const wsTimeout = setTimeout(() => {
-          abortHandler(
-            new ConnectionError(
-              'room connection has timed out (signal)',
-              ConnectionErrorReason.ServerUnreachable,
-            ),
-          );
+          abortHandler(ConnectionError.timeout('room connection has timed out (signal)'));
         }, opts.websocketTimeout);
 
         const handleSignalConnected = (
@@ -364,9 +359,8 @@ export class SignalClient {
             .then((closeInfo) => {
               if (this.isEstablishingConnection) {
                 reject(
-                  new ConnectionError(
+                  ConnectionError.internal(
                     `Websocket got closed during a (re)connection attempt: ${closeInfo.reason}`,
-                    ConnectionErrorReason.InternalError,
                   ),
                 );
               }
@@ -387,9 +381,8 @@ export class SignalClient {
             .catch((reason) => {
               if (this.isEstablishingConnection) {
                 reject(
-                  new ConnectionError(
+                  ConnectionError.internal(
                     `Websocket error during a (re)connection attempt: ${reason}`,
-                    ConnectionErrorReason.InternalError,
                   ),
                 );
               }
@@ -416,10 +409,7 @@ export class SignalClient {
           const firstMessage = await signalReader.read();
           signalReader.releaseLock();
           if (!firstMessage.value) {
-            throw new ConnectionError(
-              'no message received as first message',
-              ConnectionErrorReason.InternalError,
-            );
+            throw ConnectionError.internal('no message received as first message');
           }
 
           const firstSignalResponse = parseSignalResponse(firstMessage.value);
@@ -971,10 +961,8 @@ export class SignalClient {
     } else if (this.isEstablishingConnection && firstSignalResponse.message?.case === 'leave') {
       return {
         isValid: false,
-        error: new ConnectionError(
+        error: ConnectionError.leaveRequest(
           'Received leave request while trying to (re)connect',
-          ConnectionErrorReason.LeaveRequest,
-          undefined,
           firstSignalResponse.message.value.reason,
         ),
       };
@@ -982,16 +970,15 @@ export class SignalClient {
       // non-reconnect case, should receive join response first
       return {
         isValid: false,
-        error: new ConnectionError(
+        error: ConnectionError.internal(
           `did not receive join response, got ${firstSignalResponse.message?.case} instead`,
-          ConnectionErrorReason.InternalError,
         ),
       };
     }
 
     return {
       isValid: false,
-      error: new ConnectionError('Unexpected first message', ConnectionErrorReason.InternalError),
+      error: ConnectionError.internal('Unexpected first message'),
     };
   }
 
@@ -1010,22 +997,20 @@ export class SignalClient {
       const resp = await fetch(validateUrl);
       if (resp.status.toFixed(0).startsWith('4')) {
         const msg = await resp.text();
-        return new ConnectionError(msg, ConnectionErrorReason.NotAllowed, resp.status);
+        return ConnectionError.notAllowed(msg, resp.status);
       } else if (reason instanceof ConnectionError) {
         return reason;
       } else {
-        return new ConnectionError(
+        return ConnectionError.internal(
           `Encountered unknown websocket error during connection: ${reason}`,
-          ConnectionErrorReason.InternalError,
-          resp.status,
+          { status: resp.status, statusText: resp.statusText },
         );
       }
     } catch (e) {
       return e instanceof ConnectionError
         ? e
-        : new ConnectionError(
+        : ConnectionError.serverUnreachable(
             e instanceof Error ? e.message : 'server was not reachable',
-            ConnectionErrorReason.ServerUnreachable,
           );
     }
   }

package/src/api/utils.ts

@@ -14,7 +14,7 @@ export function createValidateUrl(rtcWsUrl: string) {
   return appendUrlPath(urlObj, 'validate');
 }
 
-function ensureTrailingSlash(path: string) {
+export function ensureTrailingSlash(path: string) {
   return path.endsWith('/') ? path : `${path}/`;
 }
 

package/src/connectionHelper/checks/turn.ts

@@ -1,4 +1,6 @@
 import { SignalClient } from '../../api/SignalClient';
+import { RegionUrlProvider } from '../../room/RegionUrlProvider';
+import { isCloud } from '../../room/utils';
 import { Checker } from './Checker';
 
 export class TURNCheck extends Checker {
@@ -7,6 +9,11 @@ export class TURNCheck extends Checker {
   }
 
   async perform(): Promise<void> {
+    if (isCloud(new URL(this.url))) {
+      this.appendMessage('Using region specific url');
+      this.url =
+        (await new RegionUrlProvider(this.url, this.token).getNextBestRegionUrl()) ?? this.url;
+    }
     const signalClient = new SignalClient();
     const joinRes = await signalClient.join(this.url, this.token, {
       autoSubscribe: true,

package/src/connectionHelper/checks/websocket.ts

@@ -1,5 +1,7 @@
-import { ServerInfo_Edition } from '@livekit/protocol';
+import { JoinResponse, ServerInfo_Edition } from '@livekit/protocol';
 import { SignalClient } from '../../api/SignalClient';
+import { RegionUrlProvider } from '../../room/RegionUrlProvider';
+import { isCloud } from '../../room/utils';
 import { Checker } from './Checker';
 
 export class WebSocketCheck extends Checker {
@@ -13,16 +15,43 @@ export class WebSocketCheck extends Checker {
     }
 
     let signalClient = new SignalClient();
-    const joinRes = await signalClient.join(this.url, this.token, {
-      autoSubscribe: true,
-      maxRetries: 0,
-      e2eeEnabled: false,
-      websocketTimeout: 15_000,
-      singlePeerConnection: false,
-    });
-    this.appendMessage(`Connected to server, version ${joinRes.serverVersion}.`);
-    if (joinRes.serverInfo?.edition === ServerInfo_Edition.Cloud && joinRes.serverInfo?.region) {
-      this.appendMessage(`LiveKit Cloud: ${joinRes.serverInfo?.region}`);
+    let joinRes: JoinResponse | undefined;
+    try {
+      joinRes = await signalClient.join(this.url, this.token, {
+        autoSubscribe: true,
+        maxRetries: 0,
+        e2eeEnabled: false,
+        websocketTimeout: 15_000,
+        singlePeerConnection: false,
+      });
+    } catch (e: any) {
+      if (isCloud(new URL(this.url))) {
+        this.appendMessage(
+          `Initial connection failed with error ${e.message}. Retrying with region fallback`,
+        );
+        const regionProvider = new RegionUrlProvider(this.url, this.token);
+        const regionUrl = await regionProvider.getNextBestRegionUrl();
+        if (regionUrl) {
+          joinRes = await signalClient.join(regionUrl, this.token, {
+            autoSubscribe: true,
+            maxRetries: 0,
+            e2eeEnabled: false,
+            websocketTimeout: 15_000,
+            singlePeerConnection: false,
+          });
+          this.appendMessage(
+            `Fallback to region worked. To avoid initial connections failing, ensure you're calling room.prepareConnection() ahead of time`,
+          );
+        }
+      }
+    }
+    if (joinRes) {
+      this.appendMessage(`Connected to server, version ${joinRes.serverVersion}.`);
+      if (joinRes.serverInfo?.edition === ServerInfo_Edition.Cloud && joinRes.serverInfo?.region) {
+        this.appendMessage(`LiveKit Cloud: ${joinRes.serverInfo?.region}`);
+      }
+    } else {
+      this.appendError(`Websocket connection could not be established`);
     }
     await signalClient.close();
   }

package/src/room/PCTransport.ts

@@ -1,8 +1,8 @@
 import { Mutex } from '@livekit/mutex';
 import { EventEmitter } from 'events';
-import type { MediaDescription, SessionDescription } from 'sdp-transform';
 import { parse, write } from 'sdp-transform';
 import { debounce } from 'ts-debounce';
+import type { MediaDescription, SessionDescription } from 'sdp-transform';
 import log, { LoggerNames, getLogger } from '../logger';
 import { NegotiationError, UnexpectedConnectionState } from './errors';
 import type { LoggerOptions } from './types';

package/src/room/PCTransportManager.ts

@@ -3,7 +3,7 @@ import { SignalTarget } from '@livekit/protocol';
 import log, { LoggerNames, getLogger } from '../logger';
 import PCTransport, { PCEvents } from './PCTransport';
 import { roomConnectOptionDefaults } from './defaults';
-import { ConnectionError, ConnectionErrorReason } from './errors';
+import { ConnectionError } from './errors';
 import CriticalTimers from './timers';
 import type { LoggerOptions } from './types';
 import { sleep } from './utils';
@@ -345,12 +345,7 @@ export class PCTransportManager {
         this.log.warn('abort transport connection', this.logContext);
         CriticalTimers.clearTimeout(connectTimeout);
 
-        reject(
-          new ConnectionError(
-            'room connection has been cancelled',
-            ConnectionErrorReason.Cancelled,
-          ),
-        );
+        reject(ConnectionError.cancelled('room connection has been cancelled'));
       };
       if (abortController?.signal.aborted) {
         abortHandler();
@@ -359,23 +354,13 @@ export class PCTransportManager {
 
       const connectTimeout = CriticalTimers.setTimeout(() => {
         abortController?.signal.removeEventListener('abort', abortHandler);
-        reject(
-          new ConnectionError(
-            'could not establish pc connection',
-            ConnectionErrorReason.InternalError,
-          ),
-        );
+        reject(ConnectionError.internal('could not establish pc connection'));
       }, timeout);
 
       while (this.state !== PCTransportState.CONNECTED) {
         await sleep(50); // FIXME we shouldn't rely on `sleep` in the connection paths, as it invokes `setTimeout` which can be drastically throttled by browser implementations
         if (abortController?.signal.aborted) {
-          reject(
-            new ConnectionError(
-              'room connection has been cancelled',
-              ConnectionErrorReason.Cancelled,
-            ),
-          );
+          reject(ConnectionError.cancelled('room connection has been cancelled'));
           return;
         }
       }