livekit-server-sdk 2.18.0 → 2.19.0

package/README.md

@@ -175,7 +175,7 @@ try {
   });
 } catch (e) {
   if (e instanceof SipCallError) {
-    console.log(e.message); // e.g. "SIP call failed: 486 Busy Here (resource_exhausted)"
+    console.log(e.message); // e.g. "SIP call failed: 486 Busy Here (failed_precondition)"
     if (e.sipStatusCode === 486) {
       // callee is busy
     }

package/dist/TwirpRPC.cjs

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var TwirpRPC_exports = {};
 __export(TwirpRPC_exports, {
+  REQUEST_ID_HEADER: () => REQUEST_ID_HEADER,
   ServerError: () => ServerError,
   SipCallError: () => SipCallError,
   TwirpError: () => TwirpError,
@@ -25,9 +26,11 @@ __export(TwirpRPC_exports, {
   livekitPackage: () => livekitPackage
 });
 module.exports = __toCommonJS(TwirpRPC_exports);
+var import_uuid = require("./crypto/uuid.cjs");
 var import_failover = require("./failover.cjs");
 var import_version = require("./version.cjs");
 const USER_AGENT = `livekit-server-sdk-node/${import_version.SDK_VERSION}`;
+const REQUEST_ID_HEADER = "X-Livekit-Request-Id";
 const defaultPrefix = "/twirp";
 const defaultTimeoutSeconds = 10;
 const livekitPackage = "livekit";
@@ -109,6 +112,7 @@ class TwirpRpc {
       "User-Agent": USER_AGENT,
       ...headers
     };
+    requestHeaders[REQUEST_ID_HEADER] = await (0, import_uuid.randomUUID)();
     const origin = new URL(this.host);
     const maxAttempts = (0, import_failover.failoverAttempts)(
       this.failover,
@@ -187,6 +191,7 @@ async function toTwirpError(response) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  REQUEST_ID_HEADER,
   ServerError,
   SipCallError,
   TwirpError,

package/dist/TwirpRPC.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/TwirpRPC.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JsonValue } from '@bufbuild/protobuf';\nimport {\n  FAILOVER_BACKOFF_BASE_MS,\n  failoverAttempts,\n  hostKey,\n  pickNext,\n  regionOrigins,\n  sleep,\n} from './failover.js';\nimport { SDK_VERSION } from './version.js';\n\n// Identifies the SDK and version to the server on every request. Browsers forbid\n// setting User-Agent via fetch and silently drop it; Node honors it.\nconst USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;\n\n// twirp RPC adapter for client implementation\n\ntype Options = {\n  /** Prefix for the RPC requests */\n  prefix?: string;\n  /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */\n  requestTimeout?: number;\n  /** Whether region failover is enabled (LiveKit Cloud hosts only). Defaults to true. */\n  failover?: boolean;\n  /** @internal test-only: force failover regardless of host. */\n  failoverForce?: boolean;\n  /** @internal test-only: base retry backoff in ms. */\n  failoverBackoffMs?: number;\n};\n\nconst defaultPrefix = '/twirp';\nconst defaultTimeoutSeconds = 10;\n\nexport const livekitPackage = 'livekit';\nexport interface Rpc {\n  request(\n    service: string,\n    method: string,\n    data: JsonValue,\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout?: number,\n  ): Promise<string>;\n}\n\nexport class ServerError extends Error {\n  status: number;\n  code?: string;\n  metadata?: Record<string, string>;\n\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(message);\n    this.name = name;\n    this.status = status;\n    this.code = code;\n    this.metadata = metadata;\n  }\n}\n\n/** @deprecated use {@link ServerError} */\nexport const TwirpError = ServerError;\n/** @deprecated use {@link ServerError} */\nexport type TwirpError = ServerError;\n\n/**\n * A {@link ServerError} from a SIP dialing call (`createSipParticipant` /\n * `transferSipParticipant`) that failed with a SIP response status. The SIP code\n * and reason are exposed as getters; any other error metadata remains available\n * via {@link ServerError.metadata}.\n */\nexport class SipCallError extends ServerError {\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(name, SipCallError.describe(message, code, metadata), status, code, metadata);\n    this.name = 'SipCallError';\n  }\n\n  /** The SIP response code of the failed call, e.g. 486 (Busy Here). */\n  get sipStatusCode(): number | undefined {\n    const raw = this.metadata?.sip_status_code;\n    return raw !== undefined ? Number(raw) : undefined;\n  }\n\n  /** The SIP reason phrase of the failed call, e.g. \"Busy Here\". */\n  get sipStatus(): string | undefined {\n    return this.metadata?.sip_status;\n  }\n\n  /** Builds a SipCallError from a ServerError, preserving its code and metadata. */\n  static fromServerError(err: ServerError): SipCallError {\n    return new SipCallError(err.name, err.message, err.status, err.code, err.metadata);\n  }\n\n  // describe renders a clear message: the SIP status, the error code, and any\n  // other metadata the server attached. Falls back to the raw message when the\n  // error carries no SIP status.\n  private static describe(fallback: string, code?: string, metadata?: Record<string, string>) {\n    const sipCode = metadata?.sip_status_code;\n    if (!sipCode) {\n      return fallback;\n    }\n    const reason = metadata?.sip_status;\n    let msg = `SIP call failed: ${sipCode}${reason ? ` ${reason}` : ''}`;\n    if (code) {\n      msg += ` (${code})`;\n    }\n    const extra = Object.entries(metadata ?? {})\n      .filter(([k]) => k !== 'sip_status_code' && k !== 'sip_status' && k !== 'error_details')\n      .map(([k, v]) => `${k}=${v}`);\n    if (extra.length) {\n      msg += ` [${extra.join(', ')}]`;\n    }\n    return msg;\n  }\n}\n\n/**\n * JSON based Twirp V7 RPC\n */\nexport class TwirpRpc {\n  host: string;\n\n  pkg: string;\n\n  prefix: string;\n\n  requestTimeout: number;\n\n  failover: boolean;\n\n  private failoverForce: boolean;\n\n  private failoverBackoffMs: number;\n\n  constructor(host: string, pkg: string, options?: Options) {\n    if (host.startsWith('ws')) {\n      host = host.replace('ws', 'http');\n    }\n    this.host = host;\n    this.pkg = pkg;\n    this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;\n    this.prefix = options?.prefix || defaultPrefix;\n    this.failover = options?.failover ?? true;\n    this.failoverForce = options?.failoverForce ?? false;\n    this.failoverBackoffMs = options?.failoverBackoffMs ?? FAILOVER_BACKOFF_BASE_MS;\n  }\n\n  /**\n   * Issues a Twirp request, failing over to alternative regions on retryable\n   * errors. On any transport error or HTTP 5xx it discovers regions via\n   * /settings/regions and replays the request — body and headers intact —\n   * against the next untried region, with exponential backoff. A 4xx is\n   * returned immediately.\n   */\n  async request(\n    service: string,\n    method: string,\n    data: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout = this.requestTimeout,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    const path = `${this.prefix}/${this.pkg}.${service}/${method}`;\n    const body = JSON.stringify(data);\n    const requestHeaders = {\n      'Content-Type': 'application/json;charset=UTF-8',\n      'User-Agent': USER_AGENT,\n      ...headers,\n    };\n\n    const origin = new URL(this.host);\n    const maxAttempts = failoverAttempts(\n      this.failover,\n      origin.hostname,\n      this.failoverForce,\n      timeout,\n    );\n    const attempted = new Set([hostKey(origin)]);\n    let regions: string[] | undefined;\n    let current = this.host;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {\n      const isLast = attempt + 1 >= maxAttempts;\n      const init: RequestInit = { method: 'POST', headers: requestHeaders, body };\n      if (timeout) {\n        init.signal = AbortSignal.timeout(timeout * 1000);\n      }\n\n      let response: Response | undefined;\n      let transportError: unknown;\n      try {\n        response = await fetch(new URL(path, current), init);\n      } catch (e) {\n        transportError = e;\n      }\n\n      if (response?.ok) {\n        // Return the raw JSON. Every caller parses it with protobuf-es\n        // fromJson(), which per the proto3 JSON spec accepts both the proto\n        // field names (snake_case) and their json_name (camelCase), so no key\n        // conversion is needed. Converting keys would also corrupt map<string,…>\n        // entries (e.g. participant attributes), whose keys are user data.\n        return (await response.json()) as Record<string, unknown>;\n      }\n\n      // Only retryable failures (a transport error or HTTP 5xx) continue;\n      // a 4xx is terminal.\n      const retryable = transportError !== undefined || (!!response && response.status >= 500);\n      let next: string | undefined;\n      if (retryable && !isLast) {\n        if (!regions) {\n          regions = await regionOrigins(origin, headers);\n        }\n        next = pickNext(regions, attempted);\n      }\n\n      if (!retryable || next === undefined) {\n        if (response) {\n          throw await toTwirpError(response);\n        }\n        throw transportError;\n      }\n\n      const reason = response ? `status ${response.status}` : transportError;\n      console.warn(\n        `livekit API request to ${new URL(current).host} failed (${reason}), retrying with fallback url ${next}`,\n      );\n      await sleep(this.failoverBackoffMs * 2 ** attempt);\n      attempted.add(hostKey(new URL(next)));\n      current = next;\n    }\n\n    throw new Error('failover loop exited without returning'); // unreachable\n  }\n}\n\n/** Builds a TwirpError from a non-2xx response, mirroring Twirp's JSON error shape. */\nasync function toTwirpError(response: Response): Promise<TwirpError> {\n  const isJson = response.headers.get('content-type') === 'application/json';\n  let errorMessage = 'Unknown internal error';\n  let errorCode: string | undefined = undefined;\n  let metadata: Record<string, string> | undefined = undefined;\n  try {\n    if (isJson) {\n      const parsedError = (await response.json()) as Record<string, unknown>;\n      if ('msg' in parsedError) {\n        errorMessage = <string>parsedError.msg;\n      }\n      if ('code' in parsedError) {\n        errorCode = <string>parsedError.code;\n      }\n      if ('meta' in parsedError) {\n        metadata = <Record<string, string>>parsedError.meta;\n      }\n    } else {\n      errorMessage = await response.text();\n    }\n  } catch (e) {\n    // parsing went wrong, no op and we keep default error message\n    console.debug(`Error when trying to parse error message, using defaults`, e);\n  }\n  return new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,sBAOO;AACP,qBAA4B;AAI5B,MAAM,aAAa,2BAA2B,0BAAW;AAiBzD,MAAM,gBAAgB;AACtB,MAAM,wBAAwB;AAEvB,MAAM,iBAAiB;AAWvB,MAAM,oBAAoB,MAAM;AAAA,EAKrC,YACE,MACA,SACA,QACA,MACA,UACA;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;AAGO,MAAM,aAAa;AAUnB,MAAM,qBAAqB,YAAY;AAAA,EAC5C,YACE,MACA,SACA,QACA,MACA,UACA;AACA,UAAM,MAAM,aAAa,SAAS,SAAS,MAAM,QAAQ,GAAG,QAAQ,MAAM,QAAQ;AAClF,SAAK,OAAO;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,gBAAoC;AA3F1C;AA4FI,UAAM,OAAM,UAAK,aAAL,mBAAe;AAC3B,WAAO,QAAQ,SAAY,OAAO,GAAG,IAAI;AAAA,EAC3C;AAAA;AAAA,EAGA,IAAI,YAAgC;AAjGtC;AAkGI,YAAO,UAAK,aAAL,mBAAe;AAAA,EACxB;AAAA;AAAA,EAGA,OAAO,gBAAgB,KAAgC;AACrD,WAAO,IAAI,aAAa,IAAI,MAAM,IAAI,SAAS,IAAI,QAAQ,IAAI,MAAM,IAAI,QAAQ;AAAA,EACnF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAe,SAAS,UAAkB,MAAe,UAAmC;AAC1F,UAAM,UAAU,qCAAU;AAC1B,QAAI,CAAC,SAAS;AACZ,aAAO;AAAA,IACT;AACA,UAAM,SAAS,qCAAU;AACzB,QAAI,MAAM,oBAAoB,OAAO,GAAG,SAAS,IAAI,MAAM,KAAK,EAAE;AAClE,QAAI,MAAM;AACR,aAAO,KAAK,IAAI;AAAA,IAClB;AACA,UAAM,QAAQ,OAAO,QAAQ,YAAY,CAAC,CAAC,EACxC,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,qBAAqB,MAAM,gBAAgB,MAAM,eAAe,EACtF,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE;AAC9B,QAAI,MAAM,QAAQ;AAChB,aAAO,KAAK,MAAM,KAAK,IAAI,CAAC;AAAA,IAC9B;AACA,WAAO;AAAA,EACT;AACF;AAKO,MAAM,SAAS;AAAA,EAepB,YAAY,MAAc,KAAa,SAAmB;AACxD,QAAI,KAAK,WAAW,IAAI,GAAG;AACzB,aAAO,KAAK,QAAQ,MAAM,MAAM;AAAA,IAClC;AACA,SAAK,OAAO;AACZ,SAAK,MAAM;AACX,SAAK,kBAAiB,mCAAS,mBAAkB;AACjD,SAAK,UAAS,mCAAS,WAAU;AACjC,SAAK,YAAW,mCAAS,aAAY;AACrC,SAAK,iBAAgB,mCAAS,kBAAiB;AAC/C,SAAK,qBAAoB,mCAAS,sBAAqB;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,QACJ,SACA,QACA,MACA,SACA,UAAU,KAAK,gBAED;AACd,UAAM,OAAO,GAAG,KAAK,MAAM,IAAI,KAAK,GAAG,IAAI,OAAO,IAAI,MAAM;AAC5D,UAAM,OAAO,KAAK,UAAU,IAAI;AAChC,UAAM,iBAAiB;AAAA,MACrB,gBAAgB;AAAA,MAChB,cAAc;AAAA,MACd,GAAG;AAAA,IACL;AAEA,UAAM,SAAS,IAAI,IAAI,KAAK,IAAI;AAChC,UAAM,kBAAc;AAAA,MAClB,KAAK;AAAA,MACL,OAAO;AAAA,MACP,KAAK;AAAA,MACL;AAAA,IACF;AACA,UAAM,YAAY,oBAAI,IAAI,KAAC,yBAAQ,MAAM,CAAC,CAAC;AAC3C,QAAI;AACJ,QAAI,UAAU,KAAK;AAEnB,aAAS,UAAU,GAAG,UAAU,aAAa,WAAW,GAAG;AACzD,YAAM,SAAS,UAAU,KAAK;AAC9B,YAAM,OAAoB,EAAE,QAAQ,QAAQ,SAAS,gBAAgB,KAAK;AAC1E,UAAI,SAAS;AACX,aAAK,SAAS,YAAY,QAAQ,UAAU,GAAI;AAAA,MAClD;AAEA,UAAI;AACJ,UAAI;AACJ,UAAI;AACF,mBAAW,MAAM,MAAM,IAAI,IAAI,MAAM,OAAO,GAAG,IAAI;AAAA,MACrD,SAAS,GAAG;AACV,yBAAiB;AAAA,MACnB;AAEA,UAAI,qCAAU,IAAI;AAMhB,eAAQ,MAAM,SAAS,KAAK;AAAA,MAC9B;AAIA,YAAM,YAAY,mBAAmB,UAAc,CAAC,CAAC,YAAY,SAAS,UAAU;AACpF,UAAI;AACJ,UAAI,aAAa,CAAC,QAAQ;AACxB,YAAI,CAAC,SAAS;AACZ,oBAAU,UAAM,+BAAc,QAAQ,OAAO;AAAA,QAC/C;AACA,mBAAO,0BAAS,SAAS,SAAS;AAAA,MACpC;AAEA,UAAI,CAAC,aAAa,SAAS,QAAW;AACpC,YAAI,UAAU;AACZ,gBAAM,MAAM,aAAa,QAAQ;AAAA,QACnC;AACA,cAAM;AAAA,MACR;AAEA,YAAM,SAAS,WAAW,UAAU,SAAS,MAAM,KAAK;AACxD,cAAQ;AAAA,QACN,0BAA0B,IAAI,IAAI,OAAO,EAAE,IAAI,YAAY,MAAM,iCAAiC,IAAI;AAAA,MACxG;AACA,gBAAM,uBAAM,KAAK,oBAAoB,KAAK,OAAO;AACjD,gBAAU,QAAI,yBAAQ,IAAI,IAAI,IAAI,CAAC,CAAC;AACpC,gBAAU;AAAA,IACZ;AAEA,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC1D;AACF;AAGA,eAAe,aAAa,UAAyC;AACnE,QAAM,SAAS,SAAS,QAAQ,IAAI,cAAc,MAAM;AACxD,MAAI,eAAe;AACnB,MAAI,YAAgC;AACpC,MAAI,WAA+C;AACnD,MAAI;AACF,QAAI,QAAQ;AACV,YAAM,cAAe,MAAM,SAAS,KAAK;AACzC,UAAI,SAAS,aAAa;AACxB,uBAAuB,YAAY;AAAA,MACrC;AACA,UAAI,UAAU,aAAa;AACzB,oBAAoB,YAAY;AAAA,MAClC;AACA,UAAI,UAAU,aAAa;AACzB,mBAAmC,YAAY;AAAA,MACjD;AAAA,IACF,OAAO;AACL,qBAAe,MAAM,SAAS,KAAK;AAAA,IACrC;AAAA,EACF,SAAS,GAAG;AAEV,YAAQ,MAAM,4DAA4D,CAAC;AAAA,EAC7E;AACA,SAAO,IAAI,WAAW,SAAS,YAAY,cAAc,SAAS,QAAQ,WAAW,QAAQ;AAC/F;","names":[]}
+{"version":3,"sources":["../src/TwirpRPC.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JsonValue } from '@bufbuild/protobuf';\nimport { randomUUID } from './crypto/uuid.js';\nimport {\n  FAILOVER_BACKOFF_BASE_MS,\n  failoverAttempts,\n  hostKey,\n  pickNext,\n  regionOrigins,\n  sleep,\n} from './failover.js';\nimport { SDK_VERSION } from './version.js';\n\n// Identifies the SDK and version to the server on every request. Browsers forbid\n// setting User-Agent via fetch and silently drop it; Node honors it.\nconst USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;\n\n// Carries a per-request idempotency key. The SDK's auto-retries (see failover)\n// keep the same key across attempts, so the server can identify and deduplicate\n// repeated requests.\nexport const REQUEST_ID_HEADER = 'X-Livekit-Request-Id';\n\n// twirp RPC adapter for client implementation\n\ntype Options = {\n  /** Prefix for the RPC requests */\n  prefix?: string;\n  /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */\n  requestTimeout?: number;\n  /** Whether region failover is enabled (LiveKit Cloud hosts only). Defaults to true. */\n  failover?: boolean;\n  /** @internal test-only: force failover regardless of host. */\n  failoverForce?: boolean;\n  /** @internal test-only: base retry backoff in ms. */\n  failoverBackoffMs?: number;\n};\n\nconst defaultPrefix = '/twirp';\nconst defaultTimeoutSeconds = 10;\n\nexport const livekitPackage = 'livekit';\nexport interface Rpc {\n  request(\n    service: string,\n    method: string,\n    data: JsonValue,\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout?: number,\n  ): Promise<string>;\n}\n\nexport class ServerError extends Error {\n  status: number;\n  code?: string;\n  metadata?: Record<string, string>;\n\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(message);\n    this.name = name;\n    this.status = status;\n    this.code = code;\n    this.metadata = metadata;\n  }\n}\n\n/** @deprecated use {@link ServerError} */\nexport const TwirpError = ServerError;\n/** @deprecated use {@link ServerError} */\nexport type TwirpError = ServerError;\n\n/**\n * A {@link ServerError} from a SIP dialing call (`createSipParticipant` /\n * `transferSipParticipant`) that failed with a SIP response status. The SIP code\n * and reason are exposed as getters; any other error metadata remains available\n * via {@link ServerError.metadata}.\n */\nexport class SipCallError extends ServerError {\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(name, SipCallError.describe(message, code, metadata), status, code, metadata);\n    this.name = 'SipCallError';\n  }\n\n  /** The SIP response code of the failed call, e.g. 486 (Busy Here). */\n  get sipStatusCode(): number | undefined {\n    const raw = this.metadata?.sip_status_code;\n    return raw !== undefined ? Number(raw) : undefined;\n  }\n\n  /** The SIP reason phrase of the failed call, e.g. \"Busy Here\". */\n  get sipStatus(): string | undefined {\n    return this.metadata?.sip_status;\n  }\n\n  /** Builds a SipCallError from a ServerError, preserving its code and metadata. */\n  static fromServerError(err: ServerError): SipCallError {\n    return new SipCallError(err.name, err.message, err.status, err.code, err.metadata);\n  }\n\n  // describe renders a clear message: the SIP status, the error code, and any\n  // other metadata the server attached. Falls back to the raw message when the\n  // error carries no SIP status.\n  private static describe(fallback: string, code?: string, metadata?: Record<string, string>) {\n    const sipCode = metadata?.sip_status_code;\n    if (!sipCode) {\n      return fallback;\n    }\n    const reason = metadata?.sip_status;\n    let msg = `SIP call failed: ${sipCode}${reason ? ` ${reason}` : ''}`;\n    if (code) {\n      msg += ` (${code})`;\n    }\n    const extra = Object.entries(metadata ?? {})\n      .filter(([k]) => k !== 'sip_status_code' && k !== 'sip_status' && k !== 'error_details')\n      .map(([k, v]) => `${k}=${v}`);\n    if (extra.length) {\n      msg += ` [${extra.join(', ')}]`;\n    }\n    return msg;\n  }\n}\n\n/**\n * JSON based Twirp V7 RPC\n */\nexport class TwirpRpc {\n  host: string;\n\n  pkg: string;\n\n  prefix: string;\n\n  requestTimeout: number;\n\n  failover: boolean;\n\n  private failoverForce: boolean;\n\n  private failoverBackoffMs: number;\n\n  constructor(host: string, pkg: string, options?: Options) {\n    if (host.startsWith('ws')) {\n      host = host.replace('ws', 'http');\n    }\n    this.host = host;\n    this.pkg = pkg;\n    this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;\n    this.prefix = options?.prefix || defaultPrefix;\n    this.failover = options?.failover ?? true;\n    this.failoverForce = options?.failoverForce ?? false;\n    this.failoverBackoffMs = options?.failoverBackoffMs ?? FAILOVER_BACKOFF_BASE_MS;\n  }\n\n  /**\n   * Issues a Twirp request, failing over to alternative regions on retryable\n   * errors. On any transport error or HTTP 5xx it discovers regions via\n   * /settings/regions and replays the request — body and headers intact —\n   * against the next untried region, with exponential backoff. A 4xx is\n   * returned immediately.\n   */\n  async request(\n    service: string,\n    method: string,\n    data: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout = this.requestTimeout,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    const path = `${this.prefix}/${this.pkg}.${service}/${method}`;\n    const body = JSON.stringify(data);\n    const requestHeaders: Record<string, string> = {\n      'Content-Type': 'application/json;charset=UTF-8',\n      'User-Agent': USER_AGENT,\n      ...headers,\n    };\n    requestHeaders[REQUEST_ID_HEADER] = await randomUUID();\n\n    const origin = new URL(this.host);\n    const maxAttempts = failoverAttempts(\n      this.failover,\n      origin.hostname,\n      this.failoverForce,\n      timeout,\n    );\n    const attempted = new Set([hostKey(origin)]);\n    let regions: string[] | undefined;\n    let current = this.host;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {\n      const isLast = attempt + 1 >= maxAttempts;\n      const init: RequestInit = { method: 'POST', headers: requestHeaders, body };\n      if (timeout) {\n        init.signal = AbortSignal.timeout(timeout * 1000);\n      }\n\n      let response: Response | undefined;\n      let transportError: unknown;\n      try {\n        response = await fetch(new URL(path, current), init);\n      } catch (e) {\n        transportError = e;\n      }\n\n      if (response?.ok) {\n        // Return the raw JSON. Every caller parses it with protobuf-es\n        // fromJson(), which per the proto3 JSON spec accepts both the proto\n        // field names (snake_case) and their json_name (camelCase), so no key\n        // conversion is needed. Converting keys would also corrupt map<string,…>\n        // entries (e.g. participant attributes), whose keys are user data.\n        return (await response.json()) as Record<string, unknown>;\n      }\n\n      // Only retryable failures (a transport error or HTTP 5xx) continue;\n      // a 4xx is terminal.\n      const retryable = transportError !== undefined || (!!response && response.status >= 500);\n      let next: string | undefined;\n      if (retryable && !isLast) {\n        if (!regions) {\n          regions = await regionOrigins(origin, headers);\n        }\n        next = pickNext(regions, attempted);\n      }\n\n      if (!retryable || next === undefined) {\n        if (response) {\n          throw await toTwirpError(response);\n        }\n        throw transportError;\n      }\n\n      const reason = response ? `status ${response.status}` : transportError;\n      console.warn(\n        `livekit API request to ${new URL(current).host} failed (${reason}), retrying with fallback url ${next}`,\n      );\n      await sleep(this.failoverBackoffMs * 2 ** attempt);\n      attempted.add(hostKey(new URL(next)));\n      current = next;\n    }\n\n    throw new Error('failover loop exited without returning'); // unreachable\n  }\n}\n\n/** Builds a TwirpError from a non-2xx response, mirroring Twirp's JSON error shape. */\nasync function toTwirpError(response: Response): Promise<TwirpError> {\n  const isJson = response.headers.get('content-type') === 'application/json';\n  let errorMessage = 'Unknown internal error';\n  let errorCode: string | undefined = undefined;\n  let metadata: Record<string, string> | undefined = undefined;\n  try {\n    if (isJson) {\n      const parsedError = (await response.json()) as Record<string, unknown>;\n      if ('msg' in parsedError) {\n        errorMessage = <string>parsedError.msg;\n      }\n      if ('code' in parsedError) {\n        errorCode = <string>parsedError.code;\n      }\n      if ('meta' in parsedError) {\n        metadata = <Record<string, string>>parsedError.meta;\n      }\n    } else {\n      errorMessage = await response.text();\n    }\n  } catch (e) {\n    // parsing went wrong, no op and we keep default error message\n    console.debug(`Error when trying to parse error message, using defaults`, e);\n  }\n  return new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);\n}\n"],"mappings":"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","names":[]}

package/dist/TwirpRPC.d.cts

@@ -1,5 +1,6 @@
 import { JsonValue } from '@bufbuild/protobuf';
 
+declare const REQUEST_ID_HEADER = "X-Livekit-Request-Id";
 type Options = {
     /** Prefix for the RPC requests */
     prefix?: string;
@@ -67,4 +68,4 @@ declare class TwirpRpc {
     timeout?: number): Promise<any>;
 }
 
-export { type Rpc, ServerError, SipCallError, TwirpError, TwirpRpc, livekitPackage };
+export { REQUEST_ID_HEADER, type Rpc, ServerError, SipCallError, TwirpError, TwirpRpc, livekitPackage };

package/dist/TwirpRPC.d.ts

@@ -1,5 +1,6 @@
 import { JsonValue } from '@bufbuild/protobuf';
 
+declare const REQUEST_ID_HEADER = "X-Livekit-Request-Id";
 type Options = {
     /** Prefix for the RPC requests */
     prefix?: string;
@@ -67,4 +68,4 @@ declare class TwirpRpc {
     timeout?: number): Promise<any>;
 }
 
-export { type Rpc, ServerError, SipCallError, TwirpError, TwirpRpc, livekitPackage };
+export { REQUEST_ID_HEADER, type Rpc, ServerError, SipCallError, TwirpError, TwirpRpc, livekitPackage };

package/dist/TwirpRPC.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TwirpRPC.d.ts","sourceRoot":"","sources":["../src/TwirpRPC.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAiBpD,KAAK,OAAO,GAAG;IACb,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAKF,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,MAAM,WAAW,GAAG;IAClB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,GAAG,EAAE,yDAAyD;IACvE,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAGhC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAQpC;AAED,0CAA0C;AAC1C,eAAO,MAAM,UAAU,oBAAc,CAAC;AACtC,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC;AAErC;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAEzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMnC,sEAAsE;IACtE,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAGtC;IAED,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,kFAAkF;IAClF,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY;IAOtD,OAAO,CAAC,MAAM,CAAC,QAAQ;CAkBxB;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,IAAI,EAAE,MAAM,CAAC;IAEb,GAAG,EAAE,MAAM,CAAC;IAEZ,MAAM,EAAE,MAAM,CAAC;IAEf,cAAc,EAAE,MAAM,CAAC;IAEvB,QAAQ,EAAE,OAAO,CAAC;IAElB,OAAO,CAAC,aAAa,CAAU;IAE/B,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAaxD;;;;;;OAMG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,GAAG,EAAE,yDAAyD;IACpE,OAAO,EAAE,GAAG,EAAE,yDAAyD;IACvE,OAAO,SAAsB,GAE5B,OAAO,CAAC,GAAG,CAAC;CAyEhB"}
+{"version":3,"file":"TwirpRPC.d.ts","sourceRoot":"","sources":["../src/TwirpRPC.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAmBpD,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AAIxD,KAAK,OAAO,GAAG;IACb,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAKF,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,MAAM,WAAW,GAAG;IAClB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,GAAG,EAAE,yDAAyD;IACvE,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAGhC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAQpC;AAED,0CAA0C;AAC1C,eAAO,MAAM,UAAU,oBAAc,CAAC;AACtC,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC;AAErC;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAEzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMnC,sEAAsE;IACtE,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAGtC;IAED,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,kFAAkF;IAClF,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY;IAOtD,OAAO,CAAC,MAAM,CAAC,QAAQ;CAkBxB;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,IAAI,EAAE,MAAM,CAAC;IAEb,GAAG,EAAE,MAAM,CAAC;IAEZ,MAAM,EAAE,MAAM,CAAC;IAEf,cAAc,EAAE,MAAM,CAAC;IAEvB,QAAQ,EAAE,OAAO,CAAC;IAElB,OAAO,CAAC,aAAa,CAAU;IAE/B,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAaxD;;;;;;OAMG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,GAAG,EAAE,yDAAyD;IACpE,OAAO,EAAE,GAAG,EAAE,yDAAyD;IACvE,OAAO,SAAsB,GAE5B,OAAO,CAAC,GAAG,CAAC;CA0EhB"}

package/dist/TwirpRPC.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "./crypto/uuid.js";
 import {
   FAILOVER_BACKOFF_BASE_MS,
   failoverAttempts,
@@ -8,6 +9,7 @@ import {
 } from "./failover.js";
 import { SDK_VERSION } from "./version.js";
 const USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;
+const REQUEST_ID_HEADER = "X-Livekit-Request-Id";
 const defaultPrefix = "/twirp";
 const defaultTimeoutSeconds = 10;
 const livekitPackage = "livekit";
@@ -89,6 +91,7 @@ class TwirpRpc {
       "User-Agent": USER_AGENT,
       ...headers
     };
+    requestHeaders[REQUEST_ID_HEADER] = await randomUUID();
     const origin = new URL(this.host);
     const maxAttempts = failoverAttempts(
       this.failover,
@@ -166,6 +169,7 @@ async function toTwirpError(response) {
   return new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);
 }
 export {
+  REQUEST_ID_HEADER,
   ServerError,
   SipCallError,
   TwirpError,

package/dist/TwirpRPC.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/TwirpRPC.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JsonValue } from '@bufbuild/protobuf';\nimport {\n  FAILOVER_BACKOFF_BASE_MS,\n  failoverAttempts,\n  hostKey,\n  pickNext,\n  regionOrigins,\n  sleep,\n} from './failover.js';\nimport { SDK_VERSION } from './version.js';\n\n// Identifies the SDK and version to the server on every request. Browsers forbid\n// setting User-Agent via fetch and silently drop it; Node honors it.\nconst USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;\n\n// twirp RPC adapter for client implementation\n\ntype Options = {\n  /** Prefix for the RPC requests */\n  prefix?: string;\n  /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */\n  requestTimeout?: number;\n  /** Whether region failover is enabled (LiveKit Cloud hosts only). Defaults to true. */\n  failover?: boolean;\n  /** @internal test-only: force failover regardless of host. */\n  failoverForce?: boolean;\n  /** @internal test-only: base retry backoff in ms. */\n  failoverBackoffMs?: number;\n};\n\nconst defaultPrefix = '/twirp';\nconst defaultTimeoutSeconds = 10;\n\nexport const livekitPackage = 'livekit';\nexport interface Rpc {\n  request(\n    service: string,\n    method: string,\n    data: JsonValue,\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout?: number,\n  ): Promise<string>;\n}\n\nexport class ServerError extends Error {\n  status: number;\n  code?: string;\n  metadata?: Record<string, string>;\n\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(message);\n    this.name = name;\n    this.status = status;\n    this.code = code;\n    this.metadata = metadata;\n  }\n}\n\n/** @deprecated use {@link ServerError} */\nexport const TwirpError = ServerError;\n/** @deprecated use {@link ServerError} */\nexport type TwirpError = ServerError;\n\n/**\n * A {@link ServerError} from a SIP dialing call (`createSipParticipant` /\n * `transferSipParticipant`) that failed with a SIP response status. The SIP code\n * and reason are exposed as getters; any other error metadata remains available\n * via {@link ServerError.metadata}.\n */\nexport class SipCallError extends ServerError {\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(name, SipCallError.describe(message, code, metadata), status, code, metadata);\n    this.name = 'SipCallError';\n  }\n\n  /** The SIP response code of the failed call, e.g. 486 (Busy Here). */\n  get sipStatusCode(): number | undefined {\n    const raw = this.metadata?.sip_status_code;\n    return raw !== undefined ? Number(raw) : undefined;\n  }\n\n  /** The SIP reason phrase of the failed call, e.g. \"Busy Here\". */\n  get sipStatus(): string | undefined {\n    return this.metadata?.sip_status;\n  }\n\n  /** Builds a SipCallError from a ServerError, preserving its code and metadata. */\n  static fromServerError(err: ServerError): SipCallError {\n    return new SipCallError(err.name, err.message, err.status, err.code, err.metadata);\n  }\n\n  // describe renders a clear message: the SIP status, the error code, and any\n  // other metadata the server attached. Falls back to the raw message when the\n  // error carries no SIP status.\n  private static describe(fallback: string, code?: string, metadata?: Record<string, string>) {\n    const sipCode = metadata?.sip_status_code;\n    if (!sipCode) {\n      return fallback;\n    }\n    const reason = metadata?.sip_status;\n    let msg = `SIP call failed: ${sipCode}${reason ? ` ${reason}` : ''}`;\n    if (code) {\n      msg += ` (${code})`;\n    }\n    const extra = Object.entries(metadata ?? {})\n      .filter(([k]) => k !== 'sip_status_code' && k !== 'sip_status' && k !== 'error_details')\n      .map(([k, v]) => `${k}=${v}`);\n    if (extra.length) {\n      msg += ` [${extra.join(', ')}]`;\n    }\n    return msg;\n  }\n}\n\n/**\n * JSON based Twirp V7 RPC\n */\nexport class TwirpRpc {\n  host: string;\n\n  pkg: string;\n\n  prefix: string;\n\n  requestTimeout: number;\n\n  failover: boolean;\n\n  private failoverForce: boolean;\n\n  private failoverBackoffMs: number;\n\n  constructor(host: string, pkg: string, options?: Options) {\n    if (host.startsWith('ws')) {\n      host = host.replace('ws', 'http');\n    }\n    this.host = host;\n    this.pkg = pkg;\n    this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;\n    this.prefix = options?.prefix || defaultPrefix;\n    this.failover = options?.failover ?? true;\n    this.failoverForce = options?.failoverForce ?? false;\n    this.failoverBackoffMs = options?.failoverBackoffMs ?? FAILOVER_BACKOFF_BASE_MS;\n  }\n\n  /**\n   * Issues a Twirp request, failing over to alternative regions on retryable\n   * errors. On any transport error or HTTP 5xx it discovers regions via\n   * /settings/regions and replays the request — body and headers intact —\n   * against the next untried region, with exponential backoff. A 4xx is\n   * returned immediately.\n   */\n  async request(\n    service: string,\n    method: string,\n    data: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout = this.requestTimeout,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    const path = `${this.prefix}/${this.pkg}.${service}/${method}`;\n    const body = JSON.stringify(data);\n    const requestHeaders = {\n      'Content-Type': 'application/json;charset=UTF-8',\n      'User-Agent': USER_AGENT,\n      ...headers,\n    };\n\n    const origin = new URL(this.host);\n    const maxAttempts = failoverAttempts(\n      this.failover,\n      origin.hostname,\n      this.failoverForce,\n      timeout,\n    );\n    const attempted = new Set([hostKey(origin)]);\n    let regions: string[] | undefined;\n    let current = this.host;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {\n      const isLast = attempt + 1 >= maxAttempts;\n      const init: RequestInit = { method: 'POST', headers: requestHeaders, body };\n      if (timeout) {\n        init.signal = AbortSignal.timeout(timeout * 1000);\n      }\n\n      let response: Response | undefined;\n      let transportError: unknown;\n      try {\n        response = await fetch(new URL(path, current), init);\n      } catch (e) {\n        transportError = e;\n      }\n\n      if (response?.ok) {\n        // Return the raw JSON. Every caller parses it with protobuf-es\n        // fromJson(), which per the proto3 JSON spec accepts both the proto\n        // field names (snake_case) and their json_name (camelCase), so no key\n        // conversion is needed. Converting keys would also corrupt map<string,…>\n        // entries (e.g. participant attributes), whose keys are user data.\n        return (await response.json()) as Record<string, unknown>;\n      }\n\n      // Only retryable failures (a transport error or HTTP 5xx) continue;\n      // a 4xx is terminal.\n      const retryable = transportError !== undefined || (!!response && response.status >= 500);\n      let next: string | undefined;\n      if (retryable && !isLast) {\n        if (!regions) {\n          regions = await regionOrigins(origin, headers);\n        }\n        next = pickNext(regions, attempted);\n      }\n\n      if (!retryable || next === undefined) {\n        if (response) {\n          throw await toTwirpError(response);\n        }\n        throw transportError;\n      }\n\n      const reason = response ? `status ${response.status}` : transportError;\n      console.warn(\n        `livekit API request to ${new URL(current).host} failed (${reason}), retrying with fallback url ${next}`,\n      );\n      await sleep(this.failoverBackoffMs * 2 ** attempt);\n      attempted.add(hostKey(new URL(next)));\n      current = next;\n    }\n\n    throw new Error('failover loop exited without returning'); // unreachable\n  }\n}\n\n/** Builds a TwirpError from a non-2xx response, mirroring Twirp's JSON error shape. */\nasync function toTwirpError(response: Response): Promise<TwirpError> {\n  const isJson = response.headers.get('content-type') === 'application/json';\n  let errorMessage = 'Unknown internal error';\n  let errorCode: string | undefined = undefined;\n  let metadata: Record<string, string> | undefined = undefined;\n  try {\n    if (isJson) {\n      const parsedError = (await response.json()) as Record<string, unknown>;\n      if ('msg' in parsedError) {\n        errorMessage = <string>parsedError.msg;\n      }\n      if ('code' in parsedError) {\n        errorCode = <string>parsedError.code;\n      }\n      if ('meta' in parsedError) {\n        metadata = <Record<string, string>>parsedError.meta;\n      }\n    } else {\n      errorMessage = await response.text();\n    }\n  } catch (e) {\n    // parsing went wrong, no op and we keep default error message\n    console.debug(`Error when trying to parse error message, using defaults`, e);\n  }\n  return new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/TwirpRPC.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { JsonValue } from '@bufbuild/protobuf';\nimport { randomUUID } from './crypto/uuid.js';\nimport {\n  FAILOVER_BACKOFF_BASE_MS,\n  failoverAttempts,\n  hostKey,\n  pickNext,\n  regionOrigins,\n  sleep,\n} from './failover.js';\nimport { SDK_VERSION } from './version.js';\n\n// Identifies the SDK and version to the server on every request. Browsers forbid\n// setting User-Agent via fetch and silently drop it; Node honors it.\nconst USER_AGENT = `livekit-server-sdk-node/${SDK_VERSION}`;\n\n// Carries a per-request idempotency key. The SDK's auto-retries (see failover)\n// keep the same key across attempts, so the server can identify and deduplicate\n// repeated requests.\nexport const REQUEST_ID_HEADER = 'X-Livekit-Request-Id';\n\n// twirp RPC adapter for client implementation\n\ntype Options = {\n  /** Prefix for the RPC requests */\n  prefix?: string;\n  /** Timeout for fetch requests, in seconds. Must be within the valid range for abort signal timeouts. */\n  requestTimeout?: number;\n  /** Whether region failover is enabled (LiveKit Cloud hosts only). Defaults to true. */\n  failover?: boolean;\n  /** @internal test-only: force failover regardless of host. */\n  failoverForce?: boolean;\n  /** @internal test-only: base retry backoff in ms. */\n  failoverBackoffMs?: number;\n};\n\nconst defaultPrefix = '/twirp';\nconst defaultTimeoutSeconds = 10;\n\nexport const livekitPackage = 'livekit';\nexport interface Rpc {\n  request(\n    service: string,\n    method: string,\n    data: JsonValue,\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout?: number,\n  ): Promise<string>;\n}\n\nexport class ServerError extends Error {\n  status: number;\n  code?: string;\n  metadata?: Record<string, string>;\n\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(message);\n    this.name = name;\n    this.status = status;\n    this.code = code;\n    this.metadata = metadata;\n  }\n}\n\n/** @deprecated use {@link ServerError} */\nexport const TwirpError = ServerError;\n/** @deprecated use {@link ServerError} */\nexport type TwirpError = ServerError;\n\n/**\n * A {@link ServerError} from a SIP dialing call (`createSipParticipant` /\n * `transferSipParticipant`) that failed with a SIP response status. The SIP code\n * and reason are exposed as getters; any other error metadata remains available\n * via {@link ServerError.metadata}.\n */\nexport class SipCallError extends ServerError {\n  constructor(\n    name: string,\n    message: string,\n    status: number,\n    code?: string,\n    metadata?: Record<string, string>,\n  ) {\n    super(name, SipCallError.describe(message, code, metadata), status, code, metadata);\n    this.name = 'SipCallError';\n  }\n\n  /** The SIP response code of the failed call, e.g. 486 (Busy Here). */\n  get sipStatusCode(): number | undefined {\n    const raw = this.metadata?.sip_status_code;\n    return raw !== undefined ? Number(raw) : undefined;\n  }\n\n  /** The SIP reason phrase of the failed call, e.g. \"Busy Here\". */\n  get sipStatus(): string | undefined {\n    return this.metadata?.sip_status;\n  }\n\n  /** Builds a SipCallError from a ServerError, preserving its code and metadata. */\n  static fromServerError(err: ServerError): SipCallError {\n    return new SipCallError(err.name, err.message, err.status, err.code, err.metadata);\n  }\n\n  // describe renders a clear message: the SIP status, the error code, and any\n  // other metadata the server attached. Falls back to the raw message when the\n  // error carries no SIP status.\n  private static describe(fallback: string, code?: string, metadata?: Record<string, string>) {\n    const sipCode = metadata?.sip_status_code;\n    if (!sipCode) {\n      return fallback;\n    }\n    const reason = metadata?.sip_status;\n    let msg = `SIP call failed: ${sipCode}${reason ? ` ${reason}` : ''}`;\n    if (code) {\n      msg += ` (${code})`;\n    }\n    const extra = Object.entries(metadata ?? {})\n      .filter(([k]) => k !== 'sip_status_code' && k !== 'sip_status' && k !== 'error_details')\n      .map(([k, v]) => `${k}=${v}`);\n    if (extra.length) {\n      msg += ` [${extra.join(', ')}]`;\n    }\n    return msg;\n  }\n}\n\n/**\n * JSON based Twirp V7 RPC\n */\nexport class TwirpRpc {\n  host: string;\n\n  pkg: string;\n\n  prefix: string;\n\n  requestTimeout: number;\n\n  failover: boolean;\n\n  private failoverForce: boolean;\n\n  private failoverBackoffMs: number;\n\n  constructor(host: string, pkg: string, options?: Options) {\n    if (host.startsWith('ws')) {\n      host = host.replace('ws', 'http');\n    }\n    this.host = host;\n    this.pkg = pkg;\n    this.requestTimeout = options?.requestTimeout ?? defaultTimeoutSeconds;\n    this.prefix = options?.prefix || defaultPrefix;\n    this.failover = options?.failover ?? true;\n    this.failoverForce = options?.failoverForce ?? false;\n    this.failoverBackoffMs = options?.failoverBackoffMs ?? FAILOVER_BACKOFF_BASE_MS;\n  }\n\n  /**\n   * Issues a Twirp request, failing over to alternative regions on retryable\n   * errors. On any transport error or HTTP 5xx it discovers regions via\n   * /settings/regions and replays the request — body and headers intact —\n   * against the next untried region, with exponential backoff. A 4xx is\n   * returned immediately.\n   */\n  async request(\n    service: string,\n    method: string,\n    data: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    headers: any, // eslint-disable-line @typescript-eslint/no-explicit-any\n    timeout = this.requestTimeout,\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    const path = `${this.prefix}/${this.pkg}.${service}/${method}`;\n    const body = JSON.stringify(data);\n    const requestHeaders: Record<string, string> = {\n      'Content-Type': 'application/json;charset=UTF-8',\n      'User-Agent': USER_AGENT,\n      ...headers,\n    };\n    requestHeaders[REQUEST_ID_HEADER] = await randomUUID();\n\n    const origin = new URL(this.host);\n    const maxAttempts = failoverAttempts(\n      this.failover,\n      origin.hostname,\n      this.failoverForce,\n      timeout,\n    );\n    const attempted = new Set([hostKey(origin)]);\n    let regions: string[] | undefined;\n    let current = this.host;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {\n      const isLast = attempt + 1 >= maxAttempts;\n      const init: RequestInit = { method: 'POST', headers: requestHeaders, body };\n      if (timeout) {\n        init.signal = AbortSignal.timeout(timeout * 1000);\n      }\n\n      let response: Response | undefined;\n      let transportError: unknown;\n      try {\n        response = await fetch(new URL(path, current), init);\n      } catch (e) {\n        transportError = e;\n      }\n\n      if (response?.ok) {\n        // Return the raw JSON. Every caller parses it with protobuf-es\n        // fromJson(), which per the proto3 JSON spec accepts both the proto\n        // field names (snake_case) and their json_name (camelCase), so no key\n        // conversion is needed. Converting keys would also corrupt map<string,…>\n        // entries (e.g. participant attributes), whose keys are user data.\n        return (await response.json()) as Record<string, unknown>;\n      }\n\n      // Only retryable failures (a transport error or HTTP 5xx) continue;\n      // a 4xx is terminal.\n      const retryable = transportError !== undefined || (!!response && response.status >= 500);\n      let next: string | undefined;\n      if (retryable && !isLast) {\n        if (!regions) {\n          regions = await regionOrigins(origin, headers);\n        }\n        next = pickNext(regions, attempted);\n      }\n\n      if (!retryable || next === undefined) {\n        if (response) {\n          throw await toTwirpError(response);\n        }\n        throw transportError;\n      }\n\n      const reason = response ? `status ${response.status}` : transportError;\n      console.warn(\n        `livekit API request to ${new URL(current).host} failed (${reason}), retrying with fallback url ${next}`,\n      );\n      await sleep(this.failoverBackoffMs * 2 ** attempt);\n      attempted.add(hostKey(new URL(next)));\n      current = next;\n    }\n\n    throw new Error('failover loop exited without returning'); // unreachable\n  }\n}\n\n/** Builds a TwirpError from a non-2xx response, mirroring Twirp's JSON error shape. */\nasync function toTwirpError(response: Response): Promise<TwirpError> {\n  const isJson = response.headers.get('content-type') === 'application/json';\n  let errorMessage = 'Unknown internal error';\n  let errorCode: string | undefined = undefined;\n  let metadata: Record<string, string> | undefined = undefined;\n  try {\n    if (isJson) {\n      const parsedError = (await response.json()) as Record<string, unknown>;\n      if ('msg' in parsedError) {\n        errorMessage = <string>parsedError.msg;\n      }\n      if ('code' in parsedError) {\n        errorCode = <string>parsedError.code;\n      }\n      if ('meta' in parsedError) {\n        metadata = <Record<string, string>>parsedError.meta;\n      }\n    } else {\n      errorMessage = await response.text();\n    }\n  } catch (e) {\n    // parsing went wrong, no op and we keep default error message\n    console.debug(`Error when trying to parse error message, using defaults`, e);\n  }\n  return new TwirpError(response.statusText, errorMessage, response.status, errorCode, metadata);\n}\n"],"mappings":"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","names":[]}

package/dist/crypto/digest.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var digest_exports = {};
 __export(digest_exports, {
@@ -33,13 +23,11 @@ __export(digest_exports, {
 module.exports = __toCommonJS(digest_exports);
 async function digest(data) {
   var _a;
-  if ((_a = globalThis.crypto) == null ? void 0 : _a.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 (!((_a = globalThis.crypto) == null ? void 0 : _a.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));
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/crypto/digest.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/crypto/digest.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Use the Web Crypto API if available, otherwise fallback to Node.js crypto\nexport async function digest(data: string): Promise<ArrayBuffer> {\n  if (globalThis.crypto?.subtle) {\n    const encoder = new TextEncoder();\n    return crypto.subtle.digest('SHA-256', encoder.encode(data));\n  } else {\n    const nodeCrypto = await import('node:crypto');\n    return nodeCrypto.createHash('sha256').update(data).digest();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,eAAsB,OAAO,MAAoC;AALjE;AAME,OAAI,gBAAW,WAAX,mBAAmB,QAAQ;AAC7B,UAAM,UAAU,IAAI,YAAY;AAChC,WAAO,OAAO,OAAO,OAAO,WAAW,QAAQ,OAAO,IAAI,CAAC;AAAA,EAC7D,OAAO;AACL,UAAM,aAAa,MAAM,OAAO,aAAa;AAC7C,WAAO,WAAW,WAAW,QAAQ,EAAE,OAAO,IAAI,EAAE,OAAO;AAAA,EAC7D;AACF;","names":[]}
+{"version":3,"sources":["../../src/crypto/digest.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Web Crypto only — no import('node:crypto') so isolate/edge bundlers can resolve this module\nexport async function digest(data: string): Promise<ArrayBuffer> {\n  if (!globalThis.crypto?.subtle) {\n    throw new Error('Web Crypto API is required (globalThis.crypto.subtle)');\n  }\n  const encoder = new TextEncoder();\n  return crypto.subtle.digest('SHA-256', encoder.encode(data));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,eAAsB,OAAO,MAAoC;AALjE;AAME,MAAI,GAAC,gBAAW,WAAX,mBAAmB,SAAQ;AAC9B,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AACA,QAAM,UAAU,IAAI,YAAY;AAChC,SAAO,OAAO,OAAO,OAAO,WAAW,QAAQ,OAAO,IAAI,CAAC;AAC7D;","names":[]}

package/dist/crypto/digest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../src/crypto/digest.ts"],"names":[],"mappings":"AAKA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAQ/D"}
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../src/crypto/digest.ts"],"names":[],"mappings":"AAKA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAM/D"}

package/dist/crypto/digest.js

@@ -1,12 +1,10 @@
 async function digest(data) {
   var _a;
-  if ((_a = globalThis.crypto) == null ? void 0 : _a.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 (!((_a = globalThis.crypto) == null ? void 0 : _a.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));
 }
 export {
   digest

package/dist/crypto/digest.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/crypto/digest.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Use the Web Crypto API if available, otherwise fallback to Node.js crypto\nexport async function digest(data: string): Promise<ArrayBuffer> {\n  if (globalThis.crypto?.subtle) {\n    const encoder = new TextEncoder();\n    return crypto.subtle.digest('SHA-256', encoder.encode(data));\n  } else {\n    const nodeCrypto = await import('node:crypto');\n    return nodeCrypto.createHash('sha256').update(data).digest();\n  }\n}\n"],"mappings":"AAKA,eAAsB,OAAO,MAAoC;AALjE;AAME,OAAI,gBAAW,WAAX,mBAAmB,QAAQ;AAC7B,UAAM,UAAU,IAAI,YAAY;AAChC,WAAO,OAAO,OAAO,OAAO,WAAW,QAAQ,OAAO,IAAI,CAAC;AAAA,EAC7D,OAAO;AACL,UAAM,aAAa,MAAM,OAAO,aAAa;AAC7C,WAAO,WAAW,WAAW,QAAQ,EAAE,OAAO,IAAI,EAAE,OAAO;AAAA,EAC7D;AACF;","names":[]}
+{"version":3,"sources":["../../src/crypto/digest.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Web Crypto only — no import('node:crypto') so isolate/edge bundlers can resolve this module\nexport async function digest(data: string): Promise<ArrayBuffer> {\n  if (!globalThis.crypto?.subtle) {\n    throw new Error('Web Crypto API is required (globalThis.crypto.subtle)');\n  }\n  const encoder = new TextEncoder();\n  return crypto.subtle.digest('SHA-256', encoder.encode(data));\n}\n"],"mappings":"AAKA,eAAsB,OAAO,MAAoC;AALjE;AAME,MAAI,GAAC,gBAAW,WAAX,mBAAmB,SAAQ;AAC9B,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AACA,QAAM,UAAU,IAAI,YAAY;AAChC,SAAO,OAAO,OAAO,OAAO,WAAW,QAAQ,OAAO,IAAI,CAAC;AAC7D;","names":[]}

package/dist/crypto/uuid.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,30 +15,40 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var uuid_exports = {};
 __export(uuid_exports, {
-  getRandomBytes: () => getRandomBytes
+  getRandomBytes: () => getRandomBytes,
+  randomUUID: () => randomUUID
 });
 module.exports = __toCommonJS(uuid_exports);
 async function getRandomBytes(size = 16) {
-  if (globalThis.crypto) {
-    return crypto.getRandomValues(new Uint8Array(size));
-  } else {
-    const nodeCrypto = await import("node:crypto");
-    return nodeCrypto.getRandomValues(new Uint8Array(size));
+  var _a;
+  if (!((_a = globalThis.crypto) == null ? void 0 : _a.getRandomValues)) {
+    throw new Error("Web Crypto API is required (globalThis.crypto.getRandomValues)");
   }
+  return crypto.getRandomValues(new Uint8Array(size));
+}
+async function randomUUID() {
+  var _a;
+  if (typeof ((_a = globalThis.crypto) == null ? void 0 : _a.randomUUID) === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = await getRandomBytes(16);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  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("-");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  getRandomBytes
+  getRandomBytes,
+  randomUUID
 });
 //# sourceMappingURL=uuid.cjs.map

package/dist/crypto/uuid.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/crypto/uuid.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Use the Web Crypto API if available, otherwise fallback to Node.js crypto\nexport async function getRandomBytes(size: number = 16): Promise<Uint8Array> {\n  if (globalThis.crypto) {\n    return crypto.getRandomValues(new Uint8Array(size));\n  } else {\n    const nodeCrypto = await import('node:crypto');\n    return nodeCrypto.getRandomValues(new Uint8Array(size));\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,eAAsB,eAAe,OAAe,IAAyB;AAC3E,MAAI,WAAW,QAAQ;AACrB,WAAO,OAAO,gBAAgB,IAAI,WAAW,IAAI,CAAC;AAAA,EACpD,OAAO;AACL,UAAM,aAAa,MAAM,OAAO,aAAa;AAC7C,WAAO,WAAW,gBAAgB,IAAI,WAAW,IAAI,CAAC;AAAA,EACxD;AACF;","names":[]}
+{"version":3,"sources":["../../src/crypto/uuid.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Web Crypto only — no import('node:crypto') so isolate/edge bundlers can resolve this module\nexport async function getRandomBytes(size: number = 16): Promise<Uint8Array> {\n  if (!globalThis.crypto?.getRandomValues) {\n    throw new Error('Web Crypto API is required (globalThis.crypto.getRandomValues)');\n  }\n  return crypto.getRandomValues(new Uint8Array(size));\n}\n\n// A random RFC 4122 v4 UUID. Prefers the platform's randomUUID (Node 19+, edge\n// runtimes, browsers in a secure context) and otherwise formats random bytes,\n// so it works everywhere getRandomBytes does.\nexport async function randomUUID(): Promise<string> {\n  if (typeof globalThis.crypto?.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  const bytes = await getRandomBytes(16);\n  bytes[6] = (bytes[6]! & 0x0f) | 0x40; // version 4\n  bytes[8] = (bytes[8]! & 0x3f) | 0x80; // variant 1\n  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n  return [\n    hex.slice(0, 8),\n    hex.slice(8, 12),\n    hex.slice(12, 16),\n    hex.slice(16, 20),\n    hex.slice(20),\n  ].join('-');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,eAAsB,eAAe,OAAe,IAAyB;AAL7E;AAME,MAAI,GAAC,gBAAW,WAAX,mBAAmB,kBAAiB;AACvC,UAAM,IAAI,MAAM,gEAAgE;AAAA,EAClF;AACA,SAAO,OAAO,gBAAgB,IAAI,WAAW,IAAI,CAAC;AACpD;AAKA,eAAsB,aAA8B;AAfpD;AAgBE,MAAI,SAAO,gBAAW,WAAX,mBAAmB,gBAAe,YAAY;AACvD,WAAO,OAAO,WAAW;AAAA,EAC3B;AACA,QAAM,QAAQ,MAAM,eAAe,EAAE;AACrC,QAAM,CAAC,IAAK,MAAM,CAAC,IAAK,KAAQ;AAChC,QAAM,CAAC,IAAK,MAAM,CAAC,IAAK,KAAQ;AAChC,QAAM,MAAM,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAAE,KAAK,EAAE;AAC7E,SAAO;AAAA,IACL,IAAI,MAAM,GAAG,CAAC;AAAA,IACd,IAAI,MAAM,GAAG,EAAE;AAAA,IACf,IAAI,MAAM,IAAI,EAAE;AAAA,IAChB,IAAI,MAAM,IAAI,EAAE;AAAA,IAChB,IAAI,MAAM,EAAE;AAAA,EACd,EAAE,KAAK,GAAG;AACZ;","names":[]}

package/dist/crypto/uuid.d.cts

@@ -1,3 +1,4 @@
 declare function getRandomBytes(size?: number): Promise<Uint8Array>;
+declare function randomUUID(): Promise<string>;
 
-export { getRandomBytes };
+export { getRandomBytes, randomUUID };

package/dist/crypto/uuid.d.ts

@@ -1,3 +1,4 @@
 declare function getRandomBytes(size?: number): Promise<Uint8Array>;
+declare function randomUUID(): Promise<string>;
 
-export { getRandomBytes };
+export { getRandomBytes, randomUUID };

package/dist/crypto/uuid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../src/crypto/uuid.ts"],"names":[],"mappings":"AAKA,wBAAsB,cAAc,CAAC,IAAI,GAAE,MAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAO3E"}
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../src/crypto/uuid.ts"],"names":[],"mappings":"AAKA,wBAAsB,cAAc,CAAC,IAAI,GAAE,MAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAK3E;AAKD,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAelD"}

package/dist/crypto/uuid.js

@@ -1,12 +1,29 @@
 async function getRandomBytes(size = 16) {
-  if (globalThis.crypto) {
-    return crypto.getRandomValues(new Uint8Array(size));
-  } else {
-    const nodeCrypto = await import("node:crypto");
-    return nodeCrypto.getRandomValues(new Uint8Array(size));
+  var _a;
+  if (!((_a = globalThis.crypto) == null ? void 0 : _a.getRandomValues)) {
+    throw new Error("Web Crypto API is required (globalThis.crypto.getRandomValues)");
   }
+  return crypto.getRandomValues(new Uint8Array(size));
+}
+async function randomUUID() {
+  var _a;
+  if (typeof ((_a = globalThis.crypto) == null ? void 0 : _a.randomUUID) === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = await getRandomBytes(16);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  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("-");
 }
 export {
-  getRandomBytes
+  getRandomBytes,
+  randomUUID
 };
 //# sourceMappingURL=uuid.js.map

package/dist/crypto/uuid.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/crypto/uuid.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Use the Web Crypto API if available, otherwise fallback to Node.js crypto\nexport async function getRandomBytes(size: number = 16): Promise<Uint8Array> {\n  if (globalThis.crypto) {\n    return crypto.getRandomValues(new Uint8Array(size));\n  } else {\n    const nodeCrypto = await import('node:crypto');\n    return nodeCrypto.getRandomValues(new Uint8Array(size));\n  }\n}\n"],"mappings":"AAKA,eAAsB,eAAe,OAAe,IAAyB;AAC3E,MAAI,WAAW,QAAQ;AACrB,WAAO,OAAO,gBAAgB,IAAI,WAAW,IAAI,CAAC;AAAA,EACpD,OAAO;AACL,UAAM,aAAa,MAAM,OAAO,aAAa;AAC7C,WAAO,WAAW,gBAAgB,IAAI,WAAW,IAAI,CAAC;AAAA,EACxD;AACF;","names":[]}
+{"version":3,"sources":["../../src/crypto/uuid.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\n\n// Web Crypto only — no import('node:crypto') so isolate/edge bundlers can resolve this module\nexport async function getRandomBytes(size: number = 16): Promise<Uint8Array> {\n  if (!globalThis.crypto?.getRandomValues) {\n    throw new Error('Web Crypto API is required (globalThis.crypto.getRandomValues)');\n  }\n  return crypto.getRandomValues(new Uint8Array(size));\n}\n\n// A random RFC 4122 v4 UUID. Prefers the platform's randomUUID (Node 19+, edge\n// runtimes, browsers in a secure context) and otherwise formats random bytes,\n// so it works everywhere getRandomBytes does.\nexport async function randomUUID(): Promise<string> {\n  if (typeof globalThis.crypto?.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  const bytes = await getRandomBytes(16);\n  bytes[6] = (bytes[6]! & 0x0f) | 0x40; // version 4\n  bytes[8] = (bytes[8]! & 0x3f) | 0x80; // variant 1\n  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n  return [\n    hex.slice(0, 8),\n    hex.slice(8, 12),\n    hex.slice(12, 16),\n    hex.slice(16, 20),\n    hex.slice(20),\n  ].join('-');\n}\n"],"mappings":"AAKA,eAAsB,eAAe,OAAe,IAAyB;AAL7E;AAME,MAAI,GAAC,gBAAW,WAAX,mBAAmB,kBAAiB;AACvC,UAAM,IAAI,MAAM,gEAAgE;AAAA,EAClF;AACA,SAAO,OAAO,gBAAgB,IAAI,WAAW,IAAI,CAAC;AACpD;AAKA,eAAsB,aAA8B;AAfpD;AAgBE,MAAI,SAAO,gBAAW,WAAX,mBAAmB,gBAAe,YAAY;AACvD,WAAO,OAAO,WAAW;AAAA,EAC3B;AACA,QAAM,QAAQ,MAAM,eAAe,EAAE;AACrC,QAAM,CAAC,IAAK,MAAM,CAAC,IAAK,KAAQ;AAChC,QAAM,CAAC,IAAK,MAAM,CAAC,IAAK,KAAQ;AAChC,QAAM,MAAM,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAAE,KAAK,EAAE;AAC7E,SAAO;AAAA,IACL,IAAI,MAAM,GAAG,CAAC;AAAA,IACd,IAAI,MAAM,GAAG,EAAE;AAAA,IACf,IAAI,MAAM,IAAI,EAAE;AAAA,IAChB,IAAI,MAAM,IAAI,EAAE;AAAA,IAChB,IAAI,MAAM,EAAE;AAAA,EACd,EAAE,KAAK,GAAG;AACZ;","names":[]}

package/dist/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "2.18.0";
+const SDK_VERSION = "2.19.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SDK_VERSION

package/dist/version.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["export const SDK_VERSION = \"2.18.0\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["export const SDK_VERSION = \"2.19.0\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,cAAc;","names":[]}

package/dist/version.d.cts

@@ -1,3 +1,3 @@
-declare const SDK_VERSION = "2.18.0";
+declare const SDK_VERSION = "2.19.0";
 
 export { SDK_VERSION };

package/dist/version.d.ts

@@ -1,3 +1,3 @@
-declare const SDK_VERSION = "2.18.0";
+declare const SDK_VERSION = "2.19.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,4 +1,4 @@
-const SDK_VERSION = "2.18.0";
+const SDK_VERSION = "2.19.0";
 export {
   SDK_VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["export const SDK_VERSION = \"2.18.0\";\n"],"mappings":"AAAO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["export const SDK_VERSION = \"2.19.0\";\n"],"mappings":"AAAO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livekit-server-sdk",
-  "version": "2.18.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/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/version.ts

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