livekit-server-sdk 2.17.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-server-sdk",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "Server-side SDK for LiveKit",
   "main": "dist/index.js",
   "require": "dist/index.cjs",
@@ -31,7 +31,7 @@
   ],
   "dependencies": {
     "@bufbuild/protobuf": "^1.10.1",
-    "@livekit/protocol": "^1.48.0",
+    "@livekit/protocol": "1.51.0",
     "jose": "^5.1.2"
   },
   "devDependencies": {
@@ -48,7 +48,7 @@
     "vitest": "^4.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=19"
   },
   "scripts": {
     "prebuild": "node -p \"'export const SDK_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'\" > src/version.ts",

package/src/EgressClient.ts

@@ -18,6 +18,7 @@ import {
   ListEgressResponse,
   ParticipantEgressRequest,
   RoomCompositeEgressRequest,
+  StartEgressRequest,
   StopEgressRequest,
   TrackCompositeEgressRequest,
   TrackEgressRequest,
@@ -580,6 +581,21 @@ export class EgressClient extends ServiceBase {
     return EgressInfo.fromJson(data, { ignoreUnknownFields: true });
   }
 
+  /**
+   * Starts an egress using the unified v2 request.
+   *
+   * @param request - the egress request
+   */
+  async startEgress(request: StartEgressRequest): Promise<EgressInfo> {
+    const data = await this.rpc.request(
+      svc,
+      'StartEgress',
+      request.toJson(),
+      await this.authHeader({ roomRecord: true }),
+    );
+    return EgressInfo.fromJson(data, { ignoreUnknownFields: true });
+  }
+
   /**
    * @param egressId -
    * @param layout -

package/src/TwirpRPC.test.ts

@@ -1,8 +1,8 @@
 // SPDX-FileCopyrightText: 2026 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { describe, expect, it } from 'vitest';
-import { ServerError, SipCallError } from './TwirpRPC.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { REQUEST_ID_HEADER, ServerError, SipCallError, TwirpRpc } from './TwirpRPC.js';
 
 describe('SipCallError', () => {
   it('renders the SIP status, Twirp code, and extra metadata', () => {
@@ -11,7 +11,7 @@ describe('SipCallError', () => {
         'Too Many Requests',
         'twirp error: sip status 486',
         429,
-        'resource_exhausted',
+        'failed_precondition',
         {
           sip_status_code: '486',
           sip_status: 'Busy Here',
@@ -30,7 +30,7 @@ describe('SipCallError', () => {
     expect(printed).toContain('SipCallError');
     expect(printed).toContain('486');
     expect(printed).toContain('Busy Here');
-    expect(printed).toContain('resource_exhausted');
+    expect(printed).toContain('failed_precondition');
     expect(printed).toContain('region=us-east'); // other metadata is surfaced
     expect(printed).not.toContain('error_details'); // opaque blob is omitted
   });
@@ -40,3 +40,75 @@ describe('SipCallError', () => {
     expect(err.message).toBe('boom');
   });
 });
+
+describe('request id', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const okResponse = () =>
+    ({ ok: true, status: 200, json: async () => ({}) }) as unknown as Response;
+
+  const errorResponse = (status: number) =>
+    ({
+      ok: false,
+      status,
+      statusText: 'Service Unavailable',
+      headers: { get: () => null },
+      text: async () => 'unavailable',
+    }) as unknown as Response;
+
+  // The header lets the server dedup a request that the SDK replayed.
+  it('stamps a request id on every call', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(okResponse());
+
+    const rpc = new TwirpRpc('https://test.livekit.cloud', 'livekit', { failover: false });
+    await rpc.request('RoomService', 'CreateRoom', {}, {});
+    await rpc.request('RoomService', 'CreateRoom', {}, {});
+
+    const ids = fetchSpy.mock.calls.map(
+      ([, init]) => (init!.headers as Record<string, string>)[REQUEST_ID_HEADER],
+    );
+    expect(ids[0]).toBeTruthy();
+    expect(ids[1]).toBeTruthy();
+    // A new logical call is a new request, so it gets its own id.
+    expect(ids[0]).not.toBe(ids[1]);
+  });
+
+  // The id is generated once per logical call, so every failover attempt must
+  // carry the same value.
+  it('keeps the same request id across failover attempts', async () => {
+    let attempt = 0;
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+      // Region discovery, not a replay of the request itself.
+      if (`${input}`.endsWith('/settings/regions')) {
+        return {
+          ok: true,
+          status: 200,
+          headers: { get: () => 'max-age=0' },
+          json: async () => ({
+            regions: [
+              { url: 'https://r1.retryid.livekit.cloud' },
+              { url: 'https://r2.retryid.livekit.cloud' },
+            ],
+          }),
+        } as unknown as Response;
+      }
+      attempt += 1;
+      return attempt < 3 ? errorResponse(503) : okResponse();
+    });
+
+    const rpc = new TwirpRpc('https://primary.retryid.livekit.cloud', 'livekit', {
+      failoverBackoffMs: 0,
+    });
+    await rpc.request('RoomService', 'CreateRoom', {}, {});
+
+    const ids = fetchSpy.mock.calls
+      .filter(([input]) => !`${input}`.endsWith('/settings/regions'))
+      .map(([, init]) => (init!.headers as Record<string, string>)[REQUEST_ID_HEADER]);
+
+    expect(ids).toHaveLength(3);
+    expect(ids[0]).toBeTruthy();
+    expect(new Set(ids).size).toBe(1);
+  });
+});

package/src/TwirpRPC.ts

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import type { JsonValue } from '@bufbuild/protobuf';
+import { randomUUID } from './crypto/uuid.js';
 import {
   FAILOVER_BACKOFF_BASE_MS,
   failoverAttempts,
@@ -16,6 +17,11 @@ import { SDK_VERSION } from './version.js';
 // setting User-Agent via fetch and silently drop it; Node honors it.
 const USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;
 
+// Carries a per-request idempotency key. The SDK's auto-retries (see failover)
+// keep the same key across attempts, so the server can identify and deduplicate
+// repeated requests.
+export const REQUEST_ID_HEADER = 'X-Livekit-Request-Id';
+
 // twirp RPC adapter for client implementation
 
 type Options = {
@@ -175,11 +181,12 @@ export class TwirpRpc {
   ): Promise<any> {
     const path = `${this.prefix}/${this.pkg}.${service}/${method}`;
     const body = JSON.stringify(data);
-    const requestHeaders = {
+    const requestHeaders: Record<string, string> = {
       'Content-Type': 'application/json;charset=UTF-8',
       'User-Agent': USER_AGENT,
       ...headers,
     };
+    requestHeaders[REQUEST_ID_HEADER] = await randomUUID();
 
     const origin = new URL(this.host);
     const maxAttempts = failoverAttempts(

package/src/crypto/digest.ts

@@ -2,13 +2,11 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-// Use the Web Crypto API if available, otherwise fallback to Node.js crypto
+// Web Crypto only — no import('node:crypto') so isolate/edge bundlers can resolve this module
 export async function digest(data: string): Promise<ArrayBuffer> {
-  if (globalThis.crypto?.subtle) {
-    const encoder = new TextEncoder();
-    return crypto.subtle.digest('SHA-256', encoder.encode(data));
-  } else {
-    const nodeCrypto = await import('node:crypto');
-    return nodeCrypto.createHash('sha256').update(data).digest();
+  if (!globalThis.crypto?.subtle) {
+    throw new Error('Web Crypto API is required (globalThis.crypto.subtle)');
   }
+  const encoder = new TextEncoder();
+  return crypto.subtle.digest('SHA-256', encoder.encode(data));
 }

package/src/crypto/uuid.ts

@@ -2,12 +2,30 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-// Use the Web Crypto API if available, otherwise fallback to Node.js crypto
+// Web Crypto only — no import('node:crypto') so isolate/edge bundlers can resolve this module
 export async function getRandomBytes(size: number = 16): Promise<Uint8Array> {
-  if (globalThis.crypto) {
-    return crypto.getRandomValues(new Uint8Array(size));
-  } else {
-    const nodeCrypto = await import('node:crypto');
-    return nodeCrypto.getRandomValues(new Uint8Array(size));
+  if (!globalThis.crypto?.getRandomValues) {
+    throw new Error('Web Crypto API is required (globalThis.crypto.getRandomValues)');
   }
+  return crypto.getRandomValues(new Uint8Array(size));
+}
+
+// A random RFC 4122 v4 UUID. Prefers the platform's randomUUID (Node 19+, edge
+// runtimes, browsers in a secure context) and otherwise formats random bytes,
+// so it works everywhere getRandomBytes does.
+export async function randomUUID(): Promise<string> {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  const bytes = await getRandomBytes(16);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80; // variant 1
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join('-');
 }

package/src/index.ts

@@ -24,6 +24,7 @@ export {
   EncodedFileType,
   EncodingOptions,
   EncodingOptionsPreset,
+  FileOutput,
   GCPUpload,
   ImageCodec,
   ImageFileSuffix,
@@ -38,10 +39,13 @@ export {
   IngressVideoEncodingPreset,
   IngressVideoOptions,
   JobRestartPolicy,
+  MediaSource,
+  Output,
   ParticipantEgressRequest,
   ParticipantInfo,
   ParticipantInfo_State,
   ParticipantPermission,
+  ParticipantVideo,
   Room,
   RoomAgentDispatch,
   RoomCompositeEgressRequest,
@@ -61,14 +65,18 @@ export {
   SIPCallStatus,
   SegmentedFileOutput,
   SegmentedFileProtocol,
+  StartEgressRequest,
+  StorageConfig,
   StreamOutput,
   StreamProtocol,
+  TemplateSource,
   TrackCompositeEgressRequest,
   TrackEgressRequest,
   TrackInfo,
   TrackSource,
   TrackType,
   WebEgressRequest,
+  WebSource,
   VideoCodec,
   WebhookConfig,
 } from '@livekit/protocol';

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "2.17.0";
+export const SDK_VERSION = "2.19.0";